@luciodale/docs-ui-kit 0.2.0

package/src/components/SEO.astro

@@ -0,0 +1,120 @@
+---
+import type { SiteConfig } from "../types/config";
+
+type Props = {
+	config: SiteConfig;
+	title: string;
+	description?: string;
+	currentPath: string;
+	type?: "website" | "article";
+	publishedDate?: string;
+	modifiedDate?: string;
+	noindex?: boolean;
+};
+
+const {
+	config,
+	title,
+	description = config.description,
+	currentPath,
+	type = "website",
+	publishedDate,
+	modifiedDate,
+	noindex = false,
+} = Astro.props;
+
+const canonicalUrl = new URL(currentPath, config.siteUrl).href;
+const ogImageUrl = config.ogImage ? new URL(config.ogImage, config.siteUrl).href : undefined;
+const fullTitle = currentPath === "/" ? title : `${title} | ${config.title}`;
+
+const jsonLd =
+	type === "article"
+		? {
+				"@context": "https://schema.org",
+				"@type": "TechArticle",
+				headline: title,
+				description,
+				url: canonicalUrl,
+				...(ogImageUrl && { image: ogImageUrl }),
+				...(config.author && {
+					author: { "@type": "Person", name: config.author },
+				}),
+				...(publishedDate && { datePublished: publishedDate }),
+				...(modifiedDate && { dateModified: modifiedDate }),
+				publisher: { "@type": "Organization", name: config.title },
+				isPartOf: {
+					"@type": "WebSite",
+					name: config.title,
+					url: config.siteUrl,
+				},
+			}
+		: {
+				"@context": "https://schema.org",
+				"@type": "WebSite",
+				name: config.title,
+				url: config.siteUrl,
+				description,
+			};
+
+const breadcrumbs = currentPath === "/" ? null : {
+	"@context": "https://schema.org",
+	"@type": "BreadcrumbList",
+	itemListElement: currentPath
+		.split("/")
+		.filter(Boolean)
+		.map((segment, i, arr) => ({
+			"@type": "ListItem",
+			position: i + 1,
+			name: segment.replace(/-/g, " ").replace(/\b\w/g, (c) => c.toUpperCase()),
+			item: new URL(arr.slice(0, i + 1).join("/"), config.siteUrl).href,
+		})),
+};
+
+const safeJsonLd = JSON.stringify(jsonLd).replace(/</g, "\\u003c");
+const safeBreadcrumbs = breadcrumbs ? JSON.stringify(breadcrumbs).replace(/</g, "\\u003c") : null;
+---
+
+<!-- Primary -->
+<title>{fullTitle}</title>
+<meta name="description" content={description} />
+{config.author && <meta name="author" content={config.author} />}
+<meta name="robots" content={noindex ? "noindex, nofollow" : "index, follow, max-image-preview:large, max-snippet:-1, max-video-preview:-1"} />
+<link rel="canonical" href={canonicalUrl} />
+
+<!-- Favicon -->
+{config.faviconSrc && <link rel="icon" href={config.faviconSrc} />}
+
+<!-- Open Graph -->
+<meta property="og:type" content={type === "article" ? "article" : "website"} />
+<meta property="og:url" content={canonicalUrl} />
+<meta property="og:title" content={fullTitle} />
+<meta property="og:description" content={description} />
+<meta property="og:site_name" content={config.title} />
+<meta property="og:locale" content="en_US" />
+{ogImageUrl && <meta property="og:image" content={ogImageUrl} />}
+{ogImageUrl && <meta property="og:image:width" content="1200" />}
+{ogImageUrl && <meta property="og:image:height" content="630" />}
+{ogImageUrl && <meta property="og:image:alt" content={title} />}
+
+<!-- Twitter -->
+<meta name="twitter:card" content={ogImageUrl ? "summary_large_image" : "summary"} />
+<meta name="twitter:title" content={fullTitle} />
+<meta name="twitter:description" content={description} />
+{ogImageUrl && <meta name="twitter:image" content={ogImageUrl} />}
+{config.twitterHandle && <meta name="twitter:site" content={config.twitterHandle} />}
+{config.twitterHandle && <meta name="twitter:creator" content={config.twitterHandle} />}
+
+<!-- Article -->
+{type === "article" && publishedDate && <meta property="article:published_time" content={publishedDate} />}
+{type === "article" && modifiedDate && <meta property="article:modified_time" content={modifiedDate} />}
+{type === "article" && config.author && <meta property="article:author" content={config.author} />}
+
+<!-- Theme -->
+<meta name="theme-color" content="#000000" />
+<meta name="color-scheme" content="dark" />
+
+<!-- JSON-LD: Page -->
+<script type="application/ld+json" set:html={safeJsonLd} />
+
+<!-- JSON-LD: Breadcrumbs -->
+{safeBreadcrumbs && <script type="application/ld+json" set:html={safeBreadcrumbs} />}

package/src/components/SearchModal.astro

@@ -0,0 +1,278 @@
+---
+// Search dialog. Uses Pagefind (loaded dynamically from /_pagefind/).
+// The consumer must run `npx pagefind --site <dist>` after building.
+// Trigger buttons live in Navbar.astro; this component renders only the dialog.
+---
+<dialog id="search-dialog">
+	<div class="search-dialog-panel">
+		<div class="search-dialog-header">
+			<svg class="search-dialog-icon" fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2.5">
+				<circle cx="11" cy="11" r="7" />
+				<line x1="16.5" y1="16.5" x2="21" y2="21" />
+			</svg>
+			<input
+				id="search-input"
+				type="text"
+				placeholder="Search documentation..."
+				autocomplete="off"
+				class="search-dialog-input"
+			/>
+			<kbd class="search-dialog-kbd">esc</kbd>
+		</div>
+		<div id="search-results" class="search-dialog-results">
+			<p class="search-dialog-placeholder">Type to search...</p>
+		</div>
+	</div>
+</dialog>
+
+<style>
+	#search-dialog {
+		position: fixed;
+		inset: 0;
+		z-index: 100;
+		margin: 0;
+		padding: 0;
+		height: 100dvh;
+		width: 100dvw;
+		max-height: 100dvh;
+		max-width: 100dvw;
+		background: transparent;
+		border: none;
+		display: none;
+	}
+
+	#search-dialog[open] {
+		display: flex;
+		align-items: flex-start;
+		justify-content: center;
+		padding-top: 12vh;
+	}
+
+	#search-dialog::backdrop {
+		background: rgb(0 0 0 / 0.6);
+		backdrop-filter: blur(8px);
+	}
+
+	.search-dialog-panel {
+		width: 100%;
+		max-width: 36rem;
+		margin-inline: 1rem;
+		border-radius: 0.75rem;
+		border: 1px solid rgb(255 255 255 / 0.1);
+		background: #0a0a0a;
+		box-shadow: 0 25px 50px -12px rgb(0 0 0 / 0.25);
+		overflow: hidden;
+	}
+
+	.search-dialog-header {
+		display: flex;
+		align-items: center;
+		gap: 0.75rem;
+		padding: 0.75rem 1rem;
+		border-bottom: 1px solid rgb(255 255 255 / 0.06);
+	}
+
+	.search-dialog-icon {
+		width: 0.875rem;
+		height: 0.875rem;
+		color: rgb(255 255 255 / 0.3);
+		flex-shrink: 0;
+	}
+
+	.search-dialog-input {
+		flex: 1;
+		background: transparent;
+		font-size: 0.875rem;
+		color: white;
+		outline: none;
+	}
+
+	.search-dialog-input::placeholder {
+		color: rgb(255 255 255 / 0.3);
+	}
+
+	.search-dialog-kbd {
+		border-radius: 0.25rem;
+		border: 1px solid rgb(255 255 255 / 0.1);
+		background: rgb(255 255 255 / 0.04);
+		padding: 0.125rem 0.375rem;
+		font-size: 10px;
+		font-family: ui-monospace, monospace;
+		color: rgb(255 255 255 / 0.3);
+	}
+
+	.search-dialog-results {
+		max-height: 50vh;
+		overflow-y: auto;
+		padding: 0.5rem;
+	}
+
+	.search-dialog-placeholder {
+		padding: 1.5rem 0.75rem;
+		text-align: center;
+		font-size: 0.875rem;
+		color: rgb(255 255 255 / 0.3);
+	}
+
+	#search-results :global(mark) {
+		background: transparent;
+		color: var(--color-accent);
+		font-weight: 600;
+	}
+</style>
+
+<script>
+	type PagefindSubResult = {
+		title: string;
+		url: string;
+		excerpt: string;
+	};
+
+	type PagefindResult = {
+		url: string;
+		excerpt: string;
+		meta?: { title?: string };
+		sub_results?: PagefindSubResult[];
+	};
+
+	type PagefindAPI = {
+		init: () => Promise<void>;
+		search: (query: string) => Promise<{ results: Array<{ data: () => Promise<PagefindResult> }> }>;
+	};
+
+	let pagefind: PagefindAPI | null = null;
+
+	async function loadPagefind(): Promise<PagefindAPI | null> {
+		if (pagefind) return pagefind;
+		try {
+			const path = "/_pagefind/pagefind.js";
+			pagefind = await import(/* @vite-ignore */ path) as PagefindAPI;
+			await pagefind.init();
+			return pagefind;
+		} catch {
+			return null;
+		}
+	}
+
+	type FlatResult = { title: string; section?: string; url: string; excerpt: string };
+
+	function flattenResults(items: PagefindResult[]): FlatResult[] {
+		const flat: FlatResult[] = [];
+		for (const item of items) {
+			const pageTitle = item.meta?.title ?? item.url;
+			if (item.sub_results && item.sub_results.length > 0) {
+				for (const sub of item.sub_results) {
+					flat.push({
+						title: sub.title || pageTitle,
+						section: sub.title && sub.title !== pageTitle ? pageTitle : undefined,
+						url: sub.url,
+						excerpt: sub.excerpt,
+					});
+				}
+			} else {
+				flat.push({ title: pageTitle, url: item.url, excerpt: item.excerpt });
+			}
+		}
+		return flat.slice(0, 10);
+	}
+
+	function renderResults(items: PagefindResult[], query: string) {
+		const container = document.getElementById("search-results");
+		if (!container) return;
+
+		const placeholderStyle = "padding: 1.5rem 0.75rem; text-align: center; font-size: 0.875rem; color: rgb(255 255 255 / 0.3);";
+
+		if (!query.trim()) {
+			container.innerHTML = `<p style="${placeholderStyle}">Type to search...</p>`;
+			return;
+		}
+
+		const flat = flattenResults(items);
+
+		if (flat.length === 0) {
+			container.innerHTML = `<p style="${placeholderStyle}">No results for &ldquo;${query.replace(/</g, "&lt;")}&rdquo;</p>`;
+			return;
+		}
+
+		container.innerHTML = flat
+			.map(
+				(r) => `
+			<a href="${r.url}" style="display: block; border-radius: 0.5rem; padding: 0.625rem 0.75rem; transition: background-color 150ms; text-decoration: none;" onmouseenter="this.style.background='rgb(255 255 255 / 0.04)'" onmouseleave="this.style.background='transparent'" data-search-result>
+				<div style="display: flex; align-items: baseline; gap: 0.5rem; margin-bottom: 0.125rem;">
+					<span style="font-size: 0.875rem; font-weight: 500; color: rgb(255 255 255 / 0.8);">${r.title}</span>
+					${r.section ? `<span style="font-size: 11px; color: rgb(255 255 255 / 0.25);">${r.section}</span>` : ""}
+				</div>
+				<div style="font-size: 0.75rem; color: rgb(255 255 255 / 0.4); line-height: 1.625; display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden;">${r.excerpt}</div>
+			</a>`,
+			)
+			.join("");
+	}
+
+	let debounceTimer: ReturnType<typeof setTimeout>;
+
+	async function handleSearch(query: string) {
+		const pf = await loadPagefind();
+		if (!pf) {
+			const container = document.getElementById("search-results");
+			if (container) {
+				container.innerHTML = '<p style="padding: 1.5rem 0.75rem; text-align: center; font-size: 0.875rem; color: rgb(255 255 255 / 0.3);">Search not available. Run <code style="font-family: ui-monospace, monospace; color: rgb(255 255 255 / 0.5);">npx pagefind</code> after building.</p>';
+			}
+			return;
+		}
+
+		if (!query.trim()) {
+			renderResults([], query);
+			return;
+		}
+
+		const { results } = await pf.search(query);
+		const items = await Promise.all(results.slice(0, 6).map((r) => r.data()));
+		renderResults(items, query);
+	}
+
+	function initSearch() {
+		const triggers = [
+			document.getElementById("search-trigger"),
+			document.getElementById("search-trigger-mobile"),
+		];
+		const dialog = document.getElementById("search-dialog") as HTMLDialogElement | null;
+		const input = document.getElementById("search-input") as HTMLInputElement | null;
+
+		function openSearch() {
+			dialog?.showModal();
+			input?.focus();
+		}
+
+		for (const trigger of triggers) {
+			trigger?.addEventListener("click", openSearch);
+		}
+
+		dialog?.addEventListener("click", (e) => {
+			if (e.target === dialog) dialog.close();
+		});
+
+		input?.addEventListener("input", () => {
+			clearTimeout(debounceTimer);
+			debounceTimer = setTimeout(() => handleSearch(input.value), 150);
+		});
+
+		document.getElementById("search-results")?.addEventListener("click", (e) => {
+			const link = (e.target as HTMLElement).closest("[data-search-result]");
+			if (link) dialog?.close();
+		});
+
+		document.addEventListener("keydown", (e) => {
+			if ((e.metaKey || e.ctrlKey) && e.key === "k") {
+				e.preventDefault();
+				if (dialog?.open) {
+					dialog.close();
+				} else {
+					openSearch();
+				}
+			}
+		});
+	}
+
+	initSearch();
+	document.addEventListener("astro:after-swap", initSearch);
+</script>

package/src/components/SectionHeading.astro

@@ -0,0 +1,11 @@
+---
+type Props = {
+	class?: string;
+};
+
+const { class: className } = Astro.props;
+---
+
+<h2 class:list={["text-2xl md:text-3xl font-semibold tracking-tight text-white mb-6", className]}>
+	<slot />
+</h2>

package/src/components/Sidebar.astro

@@ -0,0 +1,19 @@
+---
+import type { SidebarSection as SidebarSectionType } from "../types/config";
+import SidebarSection from "./SidebarSection.astro";
+
+type Props = {
+	sections: Array<SidebarSectionType>;
+	currentPath: string;
+};
+
+const { sections, currentPath } = Astro.props;
+---
+
+<aside class="w-64 shrink-0 border-r border-white/10 pt-8 pb-10 pl-6 pr-4 overflow-y-auto hidden md:block sticky top-16 h-[calc(100dvh-4rem)]">
+	<nav>
+		{sections.map((section) => (
+			<SidebarSection section={section} currentPath={currentPath} />
+		))}
+	</nav>
+</aside>

package/src/components/SidebarSection.astro

@@ -0,0 +1,39 @@
+---
+import type { SidebarSection } from "../types/config";
+
+type Props = {
+	section: SidebarSection;
+	currentPath: string;
+};
+
+const { section, currentPath } = Astro.props;
+---
+
+<details class="mb-6 group" open>
+	<summary class="flex items-center justify-between w-full py-1.5 text-xs font-semibold uppercase tracking-widest text-white/30 hover:text-white/50 transition-colors cursor-pointer list-none [&::-webkit-details-marker]:hidden">
+		{section.title}
+		<svg
+			class="w-3 h-3 transition-transform duration-150 group-open:rotate-180"
+			fill="none"
+			stroke="currentColor"
+			viewBox="0 0 24 24"
+		>
+			<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M19 9l-7 7-7-7" />
+		</svg>
+	</summary>
+	<div class="flex flex-col mt-2">
+		{section.links.map((link) => (
+			<a
+				href={link.href}
+				class:list={[
+					"block py-1.5 pl-3 text-sm border-l-2 transition-colors",
+					currentPath === link.href
+						? "border-accent text-white font-medium"
+						: "border-transparent text-white/50 hover:text-white/80 hover:border-white/20",
+				]}
+			>
+				{link.label}
+			</a>
+		))}
+	</div>
+</details>

package/src/components/TableOfContents.astro

@@ -0,0 +1,60 @@
+---
+// TOC is built client-side from [data-toc-label] elements in the DOM.
+// No props needed.
+---
+
+<nav id="toc" class="w-44 shrink-0 hidden xl:block sticky top-16 h-[calc(100dvh-4rem)] pt-8 pr-4 overflow-y-auto">
+	<div class="text-xs font-semibold uppercase tracking-widest text-white/30 mb-3">On this page</div>
+	<ul id="toc-list" class="flex flex-col gap-0.5"></ul>
+</nav>
+
+<script>
+	const ACTIVE_CLASS =
+		"block py-1 text-sm border-l-2 pl-3 transition-colors border-accent text-white font-medium";
+	const INACTIVE_CLASS =
+		"block py-1 text-sm border-l-2 pl-3 transition-colors border-transparent text-white/40 hover:text-white/60 hover:border-white/20";
+
+	function initToc() {
+		const tocList = document.getElementById("toc-list");
+		const sections = document.querySelectorAll("[data-toc-label]");
+		if (!tocList || sections.length === 0) return;
+
+		tocList.innerHTML = "";
+		const links: HTMLAnchorElement[] = [];
+
+		sections.forEach((section) => {
+			const label = section.getAttribute("data-toc-label");
+			const id = section.id;
+			if (!label || !id) return;
+
+			const li = document.createElement("li");
+			const a = document.createElement("a");
+			a.href = `#${id}`;
+			a.textContent = label;
+			a.className = INACTIVE_CLASS;
+			li.appendChild(a);
+			tocList.appendChild(li);
+			links.push(a);
+		});
+
+		const observer = new IntersectionObserver(
+			(entries) => {
+				for (const entry of entries) {
+					if (!entry.isIntersecting) continue;
+					const id = entry.target.id;
+					for (const link of links) {
+						const isActive = link.getAttribute("href") === `#${id}`;
+						link.className = isActive ? ACTIVE_CLASS : INACTIVE_CLASS;
+						if (isActive) link.scrollIntoView({ block: "nearest", behavior: "smooth" });
+					}
+				}
+			},
+			{ rootMargin: "-80px 0px -60% 0px", threshold: 0 },
+		);
+
+		sections.forEach((section) => observer.observe(section));
+	}
+
+	initToc();
+	document.addEventListener("astro:after-swap", initToc);
+</script>

package/src/components/icons/DangerIcon.astro

@@ -0,0 +1,9 @@
+---
+type Props = { class?: string };
+const { class: className = "w-3.5 h-3.5" } = Astro.props;
+---
+
+<svg class={className} fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+	<path d="M7.86 2h8.28L22 7.86v8.28L16.14 22H7.86L2 16.14V7.86L7.86 2z" />
+	<path d="M15 9l-6 6M9 9l6 6" />
+</svg>

package/src/components/icons/InfoIcon.astro

@@ -0,0 +1,9 @@
+---
+type Props = { class?: string };
+const { class: className = "w-3.5 h-3.5" } = Astro.props;
+---
+
+<svg class={className} fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+	<circle cx="12" cy="12" r="10" />
+	<path d="M12 16v-4M12 8h.01" />
+</svg>

package/src/components/icons/TipIcon.astro

@@ -0,0 +1,8 @@
+---
+type Props = { class?: string };
+const { class: className = "w-3.5 h-3.5" } = Astro.props;
+---
+
+<svg class={className} fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+	<path d="M9 18h6M10 22h4M12 2a7 7 0 014.9 12H7.1A7 7 0 0112 2z" />
+</svg>

package/src/components/icons/WarningIcon.astro

@@ -0,0 +1,9 @@
+---
+type Props = { class?: string };
+const { class: className = "w-3.5 h-3.5" } = Astro.props;
+---
+
+<svg class={className} fill="none" stroke="currentColor" viewBox="0 0 24 24" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+	<path d="M10.29 3.86L1.82 18a2 2 0 001.71 3h16.94a2 2 0 001.71-3L13.71 3.86a2 2 0 00-3.42 0z" />
+	<path d="M12 9v4M12 17h.01" />
+</svg>

package/src/styles/theme.css

@@ -0,0 +1,78 @@
+@theme {
+	/* Core Colors - docs-ui-kit brand palette */
+	--color-primary: #42170c;
+	--color-secondary: #6b7280;
+	--color-accent: #ef4723;
+	--color-accent-hover: #d63d1f;
+	--color-surface: #f9fafb;
+	--color-border: #e5e7eb;
+	--color-muted: #848d9f;
+
+	/* Typography */
+	--font-family: "Work Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+	--font-family-mono: "JetBrains Mono", "Fira Code", "Monaco", "Cascadia Code", monospace;
+}
+
+/* Base Styles */
+* {
+	box-sizing: border-box;
+}
+
+html {
+	scroll-behavior: smooth;
+	font-size: 16px;
+	font-family: var(--font-family);
+	scroll-padding-top: 100px;
+}
+
+body,
+html {
+	margin: 0;
+	padding: 0;
+}
+
+body {
+	background-color: black;
+	color: white;
+	min-height: 100dvh;
+}
+
+@media (max-width: 768px) {
+	.prose table {
+		display: block;
+		width: 100%;
+		overflow-x: auto;
+	}
+
+	.prose table thead,
+	.prose table tbody {
+		width: 100%;
+	}
+}
+
+/* Liquid Glass Border Effect */
+.liquid-glass-border {
+	position: relative;
+	background-clip: padding-box;
+}
+
+.liquid-glass-border::before {
+	content: "";
+	position: absolute;
+	inset: 0;
+	border-radius: 0.5rem;
+	padding: 0.5px;
+	background: linear-gradient(
+		135deg,
+		rgba(255, 255, 255, 0.4) 0%,
+		rgba(255, 255, 255, 0.15) 25%,
+		rgba(255, 255, 255, 0.05) 50%,
+		rgba(255, 255, 255, 0.15) 75%,
+		rgba(255, 255, 255, 0.4) 100%
+	);
+	-webkit-mask: linear-gradient(#fff 0 0) content-box, linear-gradient(#fff 0 0);
+	-webkit-mask-composite: xor;
+	mask-composite: exclude;
+	pointer-events: none;
+	z-index: 1;
+}

package/src/types/config.ts

@@ -0,0 +1,32 @@
+export type NavLink = {
+	href: string;
+	label: string;
+};
+
+export type SocialLinks = {
+	github: string;
+	linkedin?: string;
+};
+
+export type SidebarSection = {
+	title: string;
+	links: Array<NavLink>;
+};
+
+export type SiteConfig = {
+	title: string;
+	description: string;
+	siteUrl: string;
+	installCommand: string;
+	logoSrc?: string;
+	logoAlt?: string;
+	ogImage?: string;
+	faviconSrc?: string;
+	githubUrl: string;
+	author?: string;
+	twitterHandle?: string;
+	socialLinks: SocialLinks;
+	navLinks: Array<NavLink>;
+	sidebarSections: Array<SidebarSection>;
+	copyright?: string;
+};

package/src/types/props.ts

@@ -0,0 +1,7 @@
+export type PropsTableRow = {
+	name: string;
+	type: string;
+	defaultValue?: string;
+	description: string;
+	required?: boolean;
+};