feat(docs): standalone docs site chrome + category/subcategory navigation
Docs pages no longer embed the app Header (whose hx-post login form silently degraded to a native GET, leaking credentials into the URL — this page never loaded htmx). New docs-owned topbar: search, theme picker, Open App; anonymous visitors get a plain /login link. Optional-auth middleware (hand-rolled — echojwt's ErrorHandler return ends the chain, producing empty 200s) populates the user for signed-in visitors. Navigation rebuilt from the docs directory tree: 6 sections, subcategory groups, server-rendered expansion and active states. Search results are a templ partial (/docs/search/partial); code highlighting is server-side chroma (previously dead hljs CSS); prose is theme-aware via typography DEFAULT vars (prose-invert painted unreadable text under light themes). /docs renders the index directly; standalone 404 without the tailwind CDN. Tests: navigation routing/expansion (internal/docs), render pins asserting no login form/password field/app sidebar ever return on docs pages. lint-rendering: exempt *.test.ts fixtures (jsdom DOM building); docs.ts baseline 5 -> 1.
This commit is contained in:
John O'Keefe committed
1 parent
9d0ae2bcc4
commit
84cd6328f4
19 files changed
+2030
-1097
No files matched your search
+66
-107
@@ -1,42 +1,42 @@
|
||||
import { Alpine } from "./alpine";
|
||||
|
||||
// Documentation site behavior. Rendering ownership (AGENTS.md): the server
|
||||
// renders what things look like — nav markup, search results — and this
|
||||
// module only orchestrates client-local state (open/closed panels, the
|
||||
// search dropdown) and swaps in the server-rendered search partial.
|
||||
|
||||
function toggleSidebar(): void {
|
||||
const sidebar = document.getElementById("docs-sidebar");
|
||||
const overlay = document.getElementById("docs-overlay");
|
||||
if (!sidebar || !overlay) return;
|
||||
|
||||
if (sidebar && overlay) {
|
||||
sidebar.classList.toggle("translate-x-0");
|
||||
sidebar.classList.toggle("-translate-x-full");
|
||||
overlay.classList.toggle("hidden");
|
||||
}
|
||||
sidebar.classList.toggle("translate-x-0");
|
||||
sidebar.classList.toggle("-translate-x-full");
|
||||
overlay.classList.toggle("hidden");
|
||||
}
|
||||
|
||||
function toggleSection(el: HTMLElement): void {
|
||||
const items = el.nextElementSibling as HTMLElement;
|
||||
const arrow = el.querySelector(".section-arrow") as HTMLElement;
|
||||
if (!items || !arrow) return;
|
||||
function toggleCollapsible(header: HTMLElement): void {
|
||||
const items = header.nextElementSibling as HTMLElement | null;
|
||||
const arrow = header.querySelector<HTMLElement>(".section-arrow");
|
||||
if (!items) return;
|
||||
|
||||
const isCollapsed = items.getAttribute("data-collapsed") === "true";
|
||||
|
||||
if (isCollapsed) {
|
||||
items.classList.remove("hidden");
|
||||
items.setAttribute("data-collapsed", "false");
|
||||
arrow.style.transform = "rotate(0deg)";
|
||||
} else {
|
||||
items.classList.add("hidden");
|
||||
items.setAttribute("data-collapsed", "true");
|
||||
arrow.style.transform = "rotate(-90deg)";
|
||||
items.classList.toggle("hidden", !isCollapsed);
|
||||
items.setAttribute("data-collapsed", isCollapsed ? "false" : "true");
|
||||
if (arrow) {
|
||||
arrow.style.transform = isCollapsed ? "rotate(0deg)" : "rotate(-90deg)";
|
||||
}
|
||||
}
|
||||
|
||||
let docsSearchTimeout: ReturnType<typeof setTimeout> | null = null;
|
||||
let docsSearchAbort: AbortController | null = null;
|
||||
|
||||
function initializeDocsSearch(): void {
|
||||
const searchInput = document.getElementById("docs-search") as HTMLInputElement;
|
||||
const searchInput = document.getElementById("docs-search") as HTMLInputElement | null;
|
||||
const searchResults = document.getElementById("docs-search-results");
|
||||
|
||||
if (!searchInput || !searchResults) return;
|
||||
|
||||
let docsSearchTimeout: ReturnType<typeof setTimeout> | null = null;
|
||||
|
||||
searchInput.addEventListener("input", () => {
|
||||
const query = searchInput.value.trim();
|
||||
|
||||
@@ -45,118 +45,77 @@ function initializeDocsSearch(): void {
|
||||
}
|
||||
|
||||
if (query.length < 2) {
|
||||
searchResults.innerHTML = "";
|
||||
searchResults.classList.add("hidden");
|
||||
hideDocsSearchResults();
|
||||
return;
|
||||
}
|
||||
|
||||
docsSearchTimeout = setTimeout(() => {
|
||||
performDocsSearch(query);
|
||||
}, 300);
|
||||
void performDocsSearch(query);
|
||||
}, 250);
|
||||
});
|
||||
}
|
||||
|
||||
function performDocsSearch(query: string): void {
|
||||
function hideDocsSearchResults(): void {
|
||||
const searchResults = document.getElementById("docs-search-results");
|
||||
if (!searchResults) return;
|
||||
searchResults.replaceChildren();
|
||||
searchResults.classList.add("hidden");
|
||||
}
|
||||
|
||||
// performDocsSearch fetches the server-rendered results partial and swaps it
|
||||
// in verbatim. The partial is templ-rendered (DocsSearchResults); this module
|
||||
// never builds result markup itself.
|
||||
async function performDocsSearch(query: string): Promise<void> {
|
||||
const searchResults = document.getElementById("docs-search-results");
|
||||
if (!searchResults) return;
|
||||
|
||||
if (!(window as any).lunr) {
|
||||
console.warn("Lunr.js not loaded");
|
||||
return;
|
||||
}
|
||||
docsSearchAbort?.abort();
|
||||
docsSearchAbort = new AbortController();
|
||||
|
||||
try {
|
||||
const idx = (window as any).lunrIndex;
|
||||
if (!idx) {
|
||||
searchResults.innerHTML =
|
||||
'<p class="p-2 text-sm" style="color: var(--text-secondary)">Search index not loaded</p>';
|
||||
searchResults.classList.remove("hidden");
|
||||
return;
|
||||
const response = await fetch(`/docs/search/partial?q=${encodeURIComponent(query)}`, {
|
||||
signal: docsSearchAbort.signal,
|
||||
});
|
||||
if (!response.ok) {
|
||||
throw new Error(`search failed: ${response.status}`);
|
||||
}
|
||||
|
||||
const results = idx.search(query);
|
||||
|
||||
if (results.length === 0) {
|
||||
searchResults.innerHTML =
|
||||
'<p class="p-2 text-sm" style="color: var(--text-secondary)">No results found</p>';
|
||||
} else {
|
||||
searchResults.innerHTML = results
|
||||
.slice(0, 10)
|
||||
.map((result: { ref: string }) => {
|
||||
const doc = (window as any).docsData?.[result.ref];
|
||||
if (!doc) return "";
|
||||
|
||||
return `
|
||||
<a href="${result.ref}" class="block p-2 hover:bg-opacity-50 transition-colors" style="background-color: var(--bg-secondary)">
|
||||
<p class="font-medium text-sm" style="color: var(--text-primary)">${doc.title || result.ref}</p>
|
||||
${doc.section ? `<p class="text-xs" style="color: var(--text-secondary)">${doc.section}</p>` : ""}
|
||||
</a>
|
||||
`;
|
||||
})
|
||||
.join("");
|
||||
}
|
||||
|
||||
searchResults.innerHTML = await response.text();
|
||||
searchResults.classList.remove("hidden");
|
||||
} catch (error) {
|
||||
console.error("Search error:", error);
|
||||
searchResults.innerHTML =
|
||||
'<p class="p-2 text-sm" style="color: var(--text-secondary)">Search error</p>';
|
||||
if (error instanceof DOMException && error.name === "AbortError") return;
|
||||
console.error("Docs search error:", error);
|
||||
searchResults.textContent = "Search failed — try again.";
|
||||
searchResults.classList.add("px-4", "py-3", "text-sm");
|
||||
searchResults.style.color = "var(--text-secondary)";
|
||||
searchResults.classList.remove("hidden");
|
||||
}
|
||||
}
|
||||
|
||||
function highlightCurrentPage(): void {
|
||||
const currentPath = window.location.pathname;
|
||||
document.querySelectorAll(".nav-item").forEach((item) => {
|
||||
if (item.getAttribute("href") === currentPath) {
|
||||
item.classList.add("text-accent", "bg-accent/10", "border-r-2", "border-accent");
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
function initializeCodeCopyButtons(): void {
|
||||
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
||||
const hljs = (window as any).hljs;
|
||||
if (hljs) {
|
||||
hljs.highlightAll();
|
||||
document.querySelectorAll(".prose pre").forEach((pre) => {
|
||||
const wrapper = document.createElement("div");
|
||||
wrapper.className = "relative group";
|
||||
pre.parentNode?.insertBefore(wrapper, pre);
|
||||
wrapper.appendChild(pre);
|
||||
|
||||
document.querySelectorAll("pre code").forEach((block) => {
|
||||
const pre = block.parentElement;
|
||||
if (!pre) return;
|
||||
|
||||
const wrapper = document.createElement("div");
|
||||
wrapper.className = "relative group";
|
||||
pre.parentNode.insertBefore(wrapper, pre);
|
||||
wrapper.appendChild(pre);
|
||||
|
||||
const button = document.createElement("button");
|
||||
button.className =
|
||||
"absolute top-2 right-2 bg-background-secondary text-text-secondary px-2 py-1 rounded text-xs opacity-0 group-hover:opacity-100 transition-opacity border border-border hover:text-accent";
|
||||
button.textContent = "Copy";
|
||||
button.onclick = async () => {
|
||||
await navigator.clipboard.writeText(block.textContent || "");
|
||||
button.textContent = "Copied!";
|
||||
setTimeout(() => {
|
||||
button.textContent = "Copy";
|
||||
}, 2000);
|
||||
};
|
||||
wrapper.appendChild(button);
|
||||
const button = document.createElement("button");
|
||||
button.className =
|
||||
"absolute top-2 right-2 btn px-2 py-1 rounded-lg text-xs opacity-0 group-hover:opacity-100 transition-opacity";
|
||||
button.textContent = "Copy";
|
||||
button.addEventListener("click", async () => {
|
||||
await navigator.clipboard.writeText(pre.textContent || "");
|
||||
button.textContent = "Copied!";
|
||||
setTimeout(() => {
|
||||
button.textContent = "Copy";
|
||||
}, 2000);
|
||||
});
|
||||
}
|
||||
wrapper.appendChild(button);
|
||||
});
|
||||
}
|
||||
|
||||
Alpine.data("docs", () => ({
|
||||
toggleSidebar,
|
||||
toggleSection,
|
||||
toggleCollapsible,
|
||||
initializeSearch: initializeDocsSearch,
|
||||
highlightCurrentPage,
|
||||
initializeCodeCopyButtons,
|
||||
}));
|
||||
|
||||
export {
|
||||
toggleSidebar,
|
||||
toggleSection,
|
||||
initializeDocsSearch,
|
||||
highlightCurrentPage,
|
||||
initializeCodeCopyButtons,
|
||||
};
|
||||
Reference in new issue
Block a user