create-neutron 0.1.0

package/templates/docs/src/components/SidebarToggle.tsx

@@ -0,0 +1,47 @@
+import { useState } from "preact/hooks";
+
+export function SidebarToggle() {
+  const [open, setOpen] = useState(false);
+
+  function toggle() {
+    const next = !open;
+    setOpen(next);
+    const sidebar = document.querySelector(".docs-sidebar");
+    if (sidebar) {
+      sidebar.classList.toggle("is-open", next);
+    }
+  }
+
+  function close() {
+    setOpen(false);
+    const sidebar = document.querySelector(".docs-sidebar");
+    if (sidebar) {
+      sidebar.classList.remove("is-open");
+    }
+  }
+
+  return (
+    <>
+      <button
+        class="docs-mobile-toggle"
+        onClick={toggle}
+        aria-label={open ? "Close sidebar" : "Open sidebar"}
+        aria-expanded={open}
+      >
+        {open ? (
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+            <line x1="18" y1="6" x2="6" y2="18" />
+            <line x1="6" y1="6" x2="18" y2="18" />
+          </svg>
+        ) : (
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+            <line x1="3" y1="12" x2="21" y2="12" />
+            <line x1="3" y1="6" x2="21" y2="6" />
+            <line x1="3" y1="18" x2="21" y2="18" />
+          </svg>
+        )}
+      </button>
+      {open && <div class="docs-sidebar-overlay" onClick={close} />}
+    </>
+  );
+}

package/templates/docs/src/components/Steps.tsx

@@ -0,0 +1,9 @@
+import type { ComponentChildren } from "preact";
+
+export interface StepsProps {
+  children: ComponentChildren;
+}
+
+export default function Steps(props: StepsProps) {
+  return <ol class="steps">{props.children}</ol>;
+}

package/templates/docs/src/components/Tabs.tsx

@@ -0,0 +1,35 @@
+import { useState } from "preact/hooks";
+import type { ComponentChildren } from "preact";
+
+export function Tabs({ labels, children }: { labels: string[]; children: ComponentChildren }) {
+  const [active, setActive] = useState(0);
+  const panels = Array.isArray(children) ? children : [children];
+
+  return (
+    <div class="tabs">
+      <div class="tabs-bar" role="tablist">
+        {labels.map((label, i) => (
+          <button
+            key={label}
+            role="tab"
+            aria-selected={i === active}
+            class="tabs-trigger"
+            onClick={() => setActive(i)}
+          >
+            {label}
+          </button>
+        ))}
+      </div>
+      {panels.map((panel, i) => (
+        <div
+          key={i}
+          role="tabpanel"
+          class="tabs-panel"
+          hidden={i !== active}
+        >
+          {panel}
+        </div>
+      ))}
+    </div>
+  );
+}

package/templates/docs/src/components/ThemeToggle.tsx

@@ -0,0 +1,45 @@
+import { useState, useEffect } from "preact/hooks";
+
+export function ThemeToggle() {
+  const [theme, setTheme] = useState("dark");
+
+  useEffect(() => {
+    const saved = localStorage.getItem("docs-theme") || "dark";
+    setTheme(saved);
+    document.documentElement.setAttribute("data-theme", saved);
+  }, []);
+
+  function toggle() {
+    const next = theme === "dark" ? "light" : "dark";
+    setTheme(next);
+    localStorage.setItem("docs-theme", next);
+    document.documentElement.setAttribute("data-theme", next);
+  }
+
+  return (
+    <button
+      class="theme-toggle"
+      onClick={toggle}
+      aria-label={`Switch to ${theme === "dark" ? "light" : "dark"} mode`}
+      title={`Switch to ${theme === "dark" ? "light" : "dark"} mode`}
+    >
+      {theme === "dark" ? (
+        <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <circle cx="12" cy="12" r="5" />
+          <line x1="12" y1="1" x2="12" y2="3" />
+          <line x1="12" y1="21" x2="12" y2="23" />
+          <line x1="4.22" y1="4.22" x2="5.64" y2="5.64" />
+          <line x1="18.36" y1="18.36" x2="19.78" y2="19.78" />
+          <line x1="1" y1="12" x2="3" y2="12" />
+          <line x1="21" y1="12" x2="23" y2="12" />
+          <line x1="4.22" y1="19.78" x2="5.64" y2="18.36" />
+          <line x1="18.36" y1="5.64" x2="19.78" y2="4.22" />
+        </svg>
+      ) : (
+        <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" />
+        </svg>
+      )}
+    </button>
+  );
+}

package/templates/docs/src/components/Toc.tsx

@@ -0,0 +1,36 @@
+import { Island } from "@neutron-build/core/client";
+import { TocTracker } from "./TocTracker";
+
+export interface TocEntry {
+  id: string;
+  text: string;
+  level: number;
+}
+
+export function Toc({ entries }: { entries: TocEntry[] }) {
+  if (!entries || entries.length === 0) return null;
+
+  const filtered = entries.filter(
+    (entry) => entry.level === 2 || entry.level === 3
+  );
+
+  if (filtered.length === 0) return null;
+
+  return (
+    <div class="docs-toc">
+      <p class="docs-toc-title">On this page</p>
+      <nav aria-label="Table of contents">
+        {filtered.map((entry) => (
+          <a
+            key={entry.id}
+            href={`#${entry.id}`}
+            class={`docs-toc-link toc-link${entry.level === 3 ? " docs-toc-link--h3" : ""}`}
+          >
+            {entry.text}
+          </a>
+        ))}
+      </nav>
+      <Island component={TocTracker} client="idle" id="toc-tracker" />
+    </div>
+  );
+}

package/templates/docs/src/components/TocTracker.tsx

@@ -0,0 +1,35 @@
+import { useEffect } from "preact/hooks";
+
+export function TocTracker() {
+  useEffect(() => {
+    const headings = document.querySelectorAll(".prose h2[id], .prose h3[id]");
+    if (!headings.length) return;
+
+    const tocLinks = document.querySelectorAll(".toc-link");
+    if (!tocLinks.length) return;
+
+    function clearActive() {
+      tocLinks.forEach((link) => link.removeAttribute("aria-current"));
+    }
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) {
+            clearActive();
+            const id = entry.target.getAttribute("id");
+            const link = document.querySelector(`.toc-link[href="#${id}"]`);
+            if (link) link.setAttribute("aria-current", "true");
+            break;
+          }
+        }
+      },
+      { rootMargin: "-80px 0px -70% 0px", threshold: 0 },
+    );
+
+    headings.forEach((h) => observer.observe(h));
+    return () => observer.disconnect();
+  }, []);
+
+  return null;
+}

package/templates/docs/src/content/config.ts

@@ -0,0 +1,13 @@
+import { defineCollection, z } from "@neutron-build/core/content";
+
+export const collections = {
+  docs: defineCollection({
+    schema: z.object({
+      title: z.string(),
+      description: z.string().optional(),
+      sidebar_label: z.string().optional(),
+      order: z.number().optional(),
+      draft: z.boolean().default(false),
+    }),
+  }),
+};

package/templates/docs/src/content/docs/getting-started/installation.mdx

@@ -0,0 +1,18 @@
+---
+title: Installation
+description: How to install the project
+order: 1
+---
+
+# Installation
+
+Install via npm:
+
+```bash
+npm install __PACKAGE_NAME__
+```
+
+## Requirements
+
+- Node.js 20+
+- npm, pnpm, or yarn

package/templates/docs/src/content/docs/getting-started/quick-start.mdx

@@ -0,0 +1,19 @@
+---
+title: Quick Start
+description: Your first steps
+order: 2
+---
+
+# Quick Start
+
+Follow these steps to get started:
+
+1. Create a new project
+2. Install dependencies
+3. Start the dev server
+
+```bash
+npm run dev
+```
+
+Your site is now running at `http://localhost:3000`.

package/templates/docs/src/content/docs/index.mdx

@@ -0,0 +1,13 @@
+---
+title: Welcome
+description: Getting started with __PROJECT_NAME__
+order: 0
+---
+
+# Welcome to __PROJECT_NAME__
+
+This is your documentation site built with [Neutron](https://neutron.build).
+
+## Quick Start
+
+Get up and running in minutes.

package/templates/docs/src/lib/pagination.ts

@@ -0,0 +1,39 @@
+export interface PaginationLink {
+  title: string;
+  slug: string;
+}
+
+interface EntryInput {
+  slug: string;
+  data: {
+    title: string;
+    order?: number;
+  };
+}
+
+export function getPagination(
+  entries: EntryInput[],
+  currentSlug: string,
+): { prev?: PaginationLink; next?: PaginationLink } {
+  const sorted = [...entries].sort(
+    (a, b) => (a.data.order ?? 999) - (b.data.order ?? 999) || a.slug.localeCompare(b.slug),
+  );
+
+  const index = sorted.findIndex((e) => e.slug === currentSlug);
+
+  if (index === -1) {
+    return {};
+  }
+
+  const prev =
+    index > 0
+      ? { title: sorted[index - 1]!.data.title, slug: sorted[index - 1]!.slug }
+      : undefined;
+
+  const next =
+    index < sorted.length - 1
+      ? { title: sorted[index + 1]!.data.title, slug: sorted[index + 1]!.slug }
+      : undefined;
+
+  return { prev, next };
+}

package/templates/docs/src/lib/sidebar.ts

@@ -0,0 +1,100 @@
+export interface SidebarItem {
+  title: string;
+  slug: string;
+  order: number;
+  active?: boolean;
+}
+
+export interface SidebarSection {
+  title: string;
+  slug: string;
+  order: number;
+  items: SidebarItem[];
+  children: SidebarSection[];
+}
+
+interface EntryInput {
+  slug: string;
+  data: {
+    title: string;
+    sidebar_label?: string;
+    order?: number;
+  };
+}
+
+function toTitle(segment: string): string {
+  return segment
+    .replace(/[-_]/g, " ")
+    .replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+export function buildSidebarTree(
+  entries: EntryInput[],
+  activeSlug?: string,
+): SidebarSection[] {
+  const sectionMap = new Map<string, SidebarSection>();
+  const rootItems: SidebarItem[] = [];
+
+  for (const entry of entries) {
+    const parts = entry.slug.split("/");
+
+    if (parts.length === 1 || (parts.length === 2 && parts[1] === "index")) {
+      rootItems.push({
+        title: entry.data.sidebar_label || entry.data.title,
+        slug: entry.slug,
+        order: entry.data.order ?? 999,
+        active: activeSlug === entry.slug,
+      });
+      continue;
+    }
+
+    const sectionSlug = parts[0]!;
+    let section = sectionMap.get(sectionSlug);
+
+    if (!section) {
+      section = {
+        title: toTitle(sectionSlug),
+        slug: sectionSlug,
+        order: 999,
+        items: [],
+        children: [],
+      };
+      sectionMap.set(sectionSlug, section);
+    }
+
+    const isIndex = parts[parts.length - 1] === "index";
+
+    if (isIndex) {
+      section.title = entry.data.sidebar_label || entry.data.title;
+      section.order = entry.data.order ?? section.order;
+    } else {
+      section.items.push({
+        title: entry.data.sidebar_label || entry.data.title,
+        slug: entry.slug,
+        order: entry.data.order ?? 999,
+        active: activeSlug === entry.slug,
+      });
+    }
+  }
+
+  for (const section of sectionMap.values()) {
+    section.items.sort((a, b) => a.order - b.order || a.title.localeCompare(b.title));
+  }
+
+  const sections = Array.from(sectionMap.values());
+  sections.sort((a, b) => a.order - b.order || a.title.localeCompare(b.title));
+
+  if (rootItems.length > 0) {
+    rootItems.sort((a, b) => a.order - b.order || a.title.localeCompare(b.title));
+    const rootSection: SidebarSection = {
+      title: "",
+      slug: "",
+      order: -1,
+      items: rootItems,
+      children: [],
+    };
+    return [rootSection, ...sections];
+  }
+
+  return sections;
+}

package/templates/docs/src/main.tsx

@@ -0,0 +1,8 @@
+import { init, registerRoutes } from "@neutron-build/core/client";
+import { routes } from "virtual:neutron/routes";
+
+const saved = localStorage.getItem("docs-theme") || "dark";
+document.documentElement.setAttribute("data-theme", saved);
+
+registerRoutes(routes);
+void init();

package/templates/docs/src/routes/_layout.tsx

@@ -0,0 +1,27 @@
+import "../styles/docs.css";
+import { Island, ViewTransitions } from "@neutron-build/core/client";
+import { ThemeToggle } from "../components/ThemeToggle";
+
+export function head() {
+  return {
+    titleTemplate: "%s — __PROJECT_NAME__",
+    description: "__PROJECT_NAME__ Documentation",
+    htmlAttrs: { lang: "en", "data-theme": "dark" },
+    headScripts: [
+      {
+        content: `(function(){var s=localStorage.getItem("docs-theme")||"dark";document.documentElement.setAttribute("data-theme",s)})();`,
+        id: "theme-init",
+      },
+    ],
+  };
+}
+
+export default function RootLayout({ children }: { children?: unknown }) {
+  return (
+    <div class="docs-app">
+      <ViewTransitions />
+      <Island component={ThemeToggle} client="load" id="theme-toggle" />
+      {children}
+    </div>
+  );
+}

package/templates/docs/src/routes/docs/[...slug].tsx

@@ -0,0 +1,85 @@
+import { getCollection, getEntry } from "@neutron-build/core/content";
+import { extractToc } from "@neutron-build/core";
+import { calculateReadingTime } from "@neutron-build/core";
+import { Toc } from "../../components/Toc";
+import { Footer } from "../../components/Footer";
+import { Breadcrumbs } from "../../components/Breadcrumbs";
+import { getPagination } from "../../lib/pagination";
+
+export const config = { mode: "static" };
+
+export async function getStaticPaths() {
+  const docs = await getCollection("docs");
+  return {
+    paths: docs
+      .filter((d: any) => !d.data.draft)
+      .map((d: any) => ({ params: { "*": d.slug } })),
+  };
+}
+
+export async function loader({ params }: { params: Record<string, string> }) {
+  const slug = params["*"] || "index";
+  const entry = await getEntry("docs", slug);
+  if (!entry) throw new Response("Not found", { status: 404 });
+
+  const toc = extractToc(entry.html);
+  const readingTime = calculateReadingTime(entry.body);
+
+  const docs = await getCollection("docs");
+  const allEntries = docs
+    .filter((d: any) => !d.data.draft)
+    .map((d: any) => ({ slug: d.slug, data: d.data }));
+  const pagination = getPagination(allEntries, slug);
+
+  return {
+    title: entry.data.title,
+    description: entry.data.description,
+    html: entry.html,
+    slug,
+    toc,
+    readingTime,
+    pagination,
+  };
+}
+
+export function head({ data }: { data: { title: string; description?: string } }) {
+  return {
+    title: data.title,
+    description: data.description,
+  };
+}
+
+export default function DocPage({
+  data,
+}: {
+  data: {
+    title: string;
+    html: string;
+    slug: string;
+    toc: { id: string; text: string; level: number }[];
+    readingTime?: { text: string; minutes: number };
+    pagination: {
+      prev?: { title: string; slug: string };
+      next?: { title: string; slug: string };
+    };
+  };
+}) {
+  return (
+    <>
+      <div class="docs-main">
+        <Breadcrumbs slug={data.slug} />
+        <article class="prose">
+          <h1>{data.title}</h1>
+          {data.readingTime && (
+            <p class="reading-time">{data.readingTime.text}</p>
+          )}
+          <div dangerouslySetInnerHTML={{ __html: data.html }} />
+        </article>
+        <Footer prev={data.pagination.prev} next={data.pagination.next} />
+      </div>
+      <div class="docs-toc-wrapper">
+        <Toc entries={data.toc} />
+      </div>
+    </>
+  );
+}

package/templates/docs/src/routes/docs/_layout.tsx

@@ -0,0 +1,47 @@
+import { getCollection } from "@neutron-build/core/content";
+import { buildSidebarTree } from "../../lib/sidebar";
+import { Sidebar } from "../../components/Sidebar";
+import { Island } from "@neutron-build/core/client";
+import { SidebarToggle } from "../../components/SidebarToggle";
+import { Search } from "../../components/Search";
+
+export const config = { mode: "static" };
+
+export async function loader({ request }: { request: Request }) {
+  const docs = await getCollection("docs");
+  const entries = docs
+    .filter((d: any) => !d.data.draft)
+    .map((d: any) => ({ slug: d.slug, data: d.data }));
+
+  const url = new URL(request.url);
+  const activeSlug = url.pathname.replace(/^\/docs\/?/, "").replace(/\/$/, "") || "index";
+
+  const tree = buildSidebarTree(entries, activeSlug);
+  return { entries, tree };
+}
+
+export default function DocsLayout({
+  data,
+  children,
+}: {
+  data: { entries: any[]; tree: any[] };
+  children?: unknown;
+}) {
+  return (
+    <div class="docs-layout">
+      <Island component={SidebarToggle} client="load" id="sidebar-toggle" />
+      <aside class="docs-sidebar">
+        <div class="docs-sidebar-header">
+          <a href="/docs" class="docs-sidebar-logo">__PROJECT_NAME__</a>
+          <Island component={Search} client="idle" id="docs-search" props={{ entries: data.entries }} />
+        </div>
+        <nav class="docs-sidebar-nav">
+          <Sidebar tree={data.tree} />
+        </nav>
+      </aside>
+      <div class="docs-content">
+        {children}
+      </div>
+    </div>
+  );
+}