@twango/twiki 0.0.0-stage → 0.1.1

package/site/src/lib/components/SEO.svelte

@@ -0,0 +1,113 @@
+<script lang="ts">
+	import { site } from '$lib/config';
+	import { socialImageSize, socialImageUrl } from '$lib/social-image';
+	import {
+		canonicalUrl as resolveCanonical,
+		collectionSchema,
+		serializeSchema,
+		type ContentAuthor
+	} from '$lib/metadata';
+
+	interface Props {
+		title?: string;
+		description?: string;
+		canonical?: string;
+		type?: 'website' | 'article';
+		image?: string;
+		imageAlt?: string;
+		published?: string;
+		modified?: string;
+		author?: ContentAuthor;
+		tags?: string[];
+		noindex?: boolean;
+		/** JSON-LD structured data (single object or array). */
+		jsonLd?: Record<string, unknown> | Record<string, unknown>[];
+	}
+
+	const {
+		title,
+		description = site.description,
+		canonical,
+		type = 'website',
+		image,
+		imageAlt = image ? (title ?? site.name) : site.description,
+		published,
+		modified,
+		author,
+		tags = [],
+		noindex = false,
+		jsonLd
+	}: Props = $props();
+
+	const fullTitle = $derived(title ? `${title} | ${site.name}` : site.name);
+	const previewImage = $derived(image ?? socialImageUrl());
+	const canonicalUrl = $derived(canonical ? resolveCanonical(canonical) : undefined);
+	const schemas = $derived(
+		jsonLd ?? (canonical ? collectionSchema(canonical, title ?? site.name, description) : [])
+	);
+	const jsonLdScripts = $derived(noindex ? [] : Array.isArray(schemas) ? schemas : [schemas]);
+
+	// Build a <script type="application/ld+json"> tag. Split the literal closing
+	// tag so the Svelte parser doesn't terminate this script block early. The
+	// payload is our own serialized structured data, not user input.
+	function jsonLdTag(schema: Record<string, unknown>): string {
+		const open = '<' + 'script type="application/ld+json">';
+		const close = '<' + '/script>';
+		return open + serializeSchema(schema) + close;
+	}
+</script>
+
+<svelte:head>
+	<title>{fullTitle}</title>
+	<meta name="description" content={description} />
+	{#if noindex}
+		<meta name="robots" content="noindex, nofollow" />
+	{:else}
+		<meta name="robots" content="max-image-preview:large" />
+	{/if}
+	{#if canonicalUrl}
+		<link rel="canonical" href={canonicalUrl} />
+	{/if}
+
+	<!-- Open Graph -->
+	<meta property="og:title" content={fullTitle} />
+	<meta property="og:description" content={description} />
+	<meta property="og:type" content={type} />
+	<meta property="og:site_name" content={site.name} />
+	<meta property="og:locale" content={site.locale} />
+	{#if canonicalUrl}
+		<meta property="og:url" content={canonicalUrl} />
+	{/if}
+	{#if previewImage}
+		<meta property="og:image" content={previewImage} />
+		<meta property="og:image:secure_url" content={previewImage} />
+		<meta property="og:image:type" content="image/png" />
+		<meta property="og:image:width" content={String(socialImageSize.width)} />
+		<meta property="og:image:height" content={String(socialImageSize.height)} />
+		<meta property="og:image:alt" content={imageAlt} />
+	{/if}
+	{#if !noindex}
+		{#if author}<meta name="author" content={author.name} />{/if}
+		{#if published}<meta property="article:published_time" content={published} />{/if}
+		{#if modified}<meta property="article:modified_time" content={modified} />{/if}
+		{#if type === 'article'}
+			{#if author?.url}<meta property="article:author" content={author.url} />{/if}
+			{#each tags as tag}<meta property="article:tag" content={tag} />{/each}
+		{/if}
+	{/if}
+
+	<!-- Twitter Card -->
+	<meta name="twitter:card" content={previewImage ? 'summary_large_image' : 'summary'} />
+	<meta name="twitter:title" content={fullTitle} />
+	<meta name="twitter:description" content={description} />
+	{#if previewImage}
+		<meta name="twitter:image" content={previewImage} />
+		<meta name="twitter:image:alt" content={imageAlt} />
+	{/if}
+
+	<!-- JSON-LD -->
+	{#each jsonLdScripts as schema (schema)}
+		<!-- eslint-disable-next-line svelte/no-at-html-tags -->
+		{@html jsonLdTag(schema)}
+	{/each}
+</svelte:head>

package/site/src/lib/components/doc/AccessLink.svelte

@@ -0,0 +1,27 @@
+<script lang="ts">
+	import { onMount } from 'svelte';
+	import { authEnabled } from '$lib/config';
+	import UsersRound from '@lucide/svelte/icons/users-round';
+
+	let owner = $state(false);
+	onMount(() => {
+		if (!authEnabled) return;
+		const controller = new AbortController();
+		fetch('/api/access', { signal: controller.signal })
+			.then(async (response) => {
+				if (response.ok) owner = (await response.json()).role === 'owner';
+			})
+			.catch(() => {});
+		return () => controller.abort();
+	});
+</script>
+
+{#if owner}
+	<a
+		href="/admin/access"
+		aria-label="Manage access"
+		title="Manage access"
+		class="inline-flex size-9 shrink-0 items-center justify-center rounded-lg text-muted hover:bg-surface hover:text-text focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none"
+		><UsersRound size={16} /></a
+	>
+{/if}

package/site/src/lib/components/doc/Backlinks.svelte

@@ -0,0 +1,59 @@
+<script lang="ts">
+	// Backlinks panel — pages that link to the current one, styled as
+	// cca-aesthetic cards (1px border-border, rounded, surface hover, accent on
+	// hover) to match DocPager.
+	import CornerDownRight from '@lucide/svelte/icons/corner-down-right';
+	import type { BacklinkRef } from '$lib/types';
+
+	interface Props {
+		backlinks: BacklinkRef[];
+	}
+
+	const { backlinks }: Props = $props();
+
+	/** Backlink slugs are display-form: '/' = home, folder pages end in '/'. */
+	function href(slug: string): string {
+		if (slug === '/') return '/';
+		return '/' + slug.replace(/\/$/, '');
+	}
+
+	/** Parent path of the linking page, shown as context under the title. */
+	function context(slug: string): string {
+		if (slug === '/') return '';
+		const segments = slug.replace(/\/$/, '').split('/');
+		return segments.slice(0, -1).join(' / ');
+	}
+</script>
+
+{#if backlinks.length > 0}
+	<section class="mt-8 border-t border-border pt-4" data-island="backlinks" aria-label="Backlinks">
+		<h2 class="m-0 mb-3 text-xs font-semibold tracking-[0.08em] text-muted uppercase">
+			Linked to this page
+		</h2>
+		<ul class="m-0 grid list-none grid-cols-2 gap-2 p-0 max-[640px]:grid-cols-1">
+			{#each backlinks as link (link.slug)}
+				<li class="min-w-0">
+					<a
+						class="group flex items-center gap-3 rounded-md border border-border px-3 py-2 no-underline transition-colors hover:border-accent hover:bg-surface focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none"
+						href={href(link.slug)}
+					>
+						<CornerDownRight
+							class="size-4 shrink-0 text-muted transition-colors group-hover:text-accent"
+							aria-hidden="true"
+						/>
+						<span class="min-w-0 flex-1">
+							<span
+								class="block truncate text-sm leading-snug font-medium text-text group-hover:text-accent"
+							>
+								{link.title}
+							</span>
+							{#if context(link.slug)}
+								<span class="block truncate text-xs text-muted">{context(link.slug)}</span>
+							{/if}
+						</span>
+					</a>
+				</li>
+			{/each}
+		</ul>
+	</section>
+{/if}

package/site/src/lib/components/doc/Breadcrumbs.svelte

@@ -0,0 +1,29 @@
+<script lang="ts">
+	import { breadcrumbs } from '$lib/metadata';
+	interface Props {
+		/** Display route of the current page, no leading slash ('' = home). */
+		route: string;
+		/** Title for the final (unlinked) crumb. */
+		current: string;
+	}
+
+	const { route, current }: Props = $props();
+
+	const crumbs = $derived(breadcrumbs(route, current).slice(1, -1));
+</script>
+
+{#if route !== ''}
+	<nav class="mb-3 text-[0.8125rem] text-muted" aria-label="Breadcrumbs">
+		<ol class="m-0 flex list-none flex-wrap items-center gap-1 p-0">
+			<li><a class="text-muted no-underline hover:text-accent" href="/">Home</a></li>
+			{#each crumbs as crumb (crumb.href)}
+				<li aria-hidden="true" class="select-none">❯</li>
+				<li>
+					<a class="text-muted no-underline hover:text-accent" href={crumb.href}>{crumb.label}</a>
+				</li>
+			{/each}
+			<li aria-hidden="true" class="select-none">❯</li>
+			<li aria-current="page" class="text-text">{current}</li>
+		</ol>
+	</nav>
+{/if}

package/site/src/lib/components/doc/ContentMeta.svelte

@@ -0,0 +1,61 @@
+<script lang="ts">
+	import PublicationBadge from './PublicationBadge.svelte';
+	import type { PagePublication } from '$lib/types';
+	import type { ContentAuthor } from '$lib/metadata';
+	interface Props {
+		modified?: string;
+		published?: string;
+		author?: ContentAuthor;
+		curated?: boolean;
+		/** Reading time in minutes. */
+		readingTime?: number;
+		publication?: PagePublication;
+	}
+
+	const {
+		modified,
+		published,
+		author,
+		curated = false,
+		readingTime,
+		publication
+	}: Props = $props();
+	const publishedLabel = $derived(
+		published
+			? new Date(published).toLocaleDateString('en-US', {
+					year: 'numeric',
+					month: 'short',
+					day: 'numeric',
+					timeZone: 'UTC'
+				})
+			: undefined
+	);
+
+	const formatted = $derived(
+		modified
+			? new Date(modified).toLocaleDateString('en-US', {
+					year: 'numeric',
+					month: 'short',
+					day: 'numeric',
+					timeZone: 'UTC'
+				})
+			: undefined
+	);
+</script>
+
+{#if formatted || readingTime || publication}
+	<p class="m-0 flex flex-wrap items-center gap-x-2 gap-y-1 text-[0.8125rem] text-muted">
+		{#if author}
+			<span
+				>{curated ? 'Curated by' : 'By'}
+				{#if author.url}<a href={author.url} rel="author">{author.name}</a>{:else}{author.name}{/if}
+			</span>
+		{/if}
+		{#if publishedLabel}<span>Published: <time datetime={published}>{publishedLabel}</time></span
+			>{/if}
+		{#if formatted}<span>Last modified: <time datetime={modified}>{formatted}</time></span>{/if}
+		{#if formatted && readingTime}<span aria-hidden="true"> · </span>{/if}
+		{#if readingTime}<span>{readingTime} min read</span>{/if}
+		{#if publication}<PublicationBadge {publication} />{/if}
+	</p>
+{/if}

package/site/src/lib/components/doc/DocPager.svelte

@@ -0,0 +1,91 @@
+<script lang="ts">
+	import { page } from '$app/state';
+	import ChevronLeft from '@lucide/svelte/icons/chevron-left';
+	import ChevronRight from '@lucide/svelte/icons/chevron-right';
+	import type { NavNode } from '$lib/types';
+	import { cn } from '$lib/utils';
+
+	interface Props {
+		nav: NavNode[];
+	}
+
+	interface PagerItem {
+		title: string;
+		route: string;
+	}
+
+	const { nav }: Props = $props();
+
+	const pages = $derived(flattenNav(nav));
+	const currentRoute = $derived(normalizeRoute(page.url.pathname));
+	const currentIndex = $derived(pages.findIndex((item) => item.route === currentRoute));
+	const previousPage = $derived(currentIndex > 0 ? pages[currentIndex - 1] : undefined);
+	const nextPage = $derived(
+		currentIndex >= 0 && currentIndex < pages.length - 1 ? pages[currentIndex + 1] : undefined
+	);
+
+	function flattenNav(nodes: NavNode[]): PagerItem[] {
+		const items: PagerItem[] = [];
+		const seenRoutes = new Set<string>();
+
+		function visit(node: NavNode): void {
+			if (node.route) {
+				const route = normalizeRoute(node.route);
+				if (!seenRoutes.has(route)) {
+					seenRoutes.add(route);
+					items.push({ title: node.title, route });
+				}
+			}
+
+			for (const child of node.children) visit(child);
+		}
+
+		for (const node of nodes) visit(node);
+		return items;
+	}
+
+	/** trailingSlash is 'never' on this site: compare routes without it. */
+	function normalizeRoute(path: string): string {
+		let normalized = path.startsWith('/') ? path : `/${path}`;
+		if (normalized.length > 1 && normalized.endsWith('/')) normalized = normalized.slice(0, -1);
+		return normalized;
+	}
+
+	const linkClass =
+		'group flex min-h-16 items-center gap-3 rounded-md border border-border px-4 py-3 no-underline transition-colors hover:border-accent hover:bg-surface focus-visible:ring-2 focus-visible:ring-accent focus-visible:outline-none';
+	const labelClass = 'block text-xs font-semibold uppercase text-muted';
+	const titleClass = 'block text-sm font-semibold leading-snug text-text group-hover:text-accent';
+</script>
+
+{#if previousPage || nextPage}
+	<nav
+		class="mt-8 grid grid-cols-2 gap-3 border-t border-border pt-4 max-[640px]:grid-cols-1"
+		aria-label="Page navigation"
+	>
+		{#if previousPage}
+			<a class={linkClass} href={previousPage.route}>
+				<ChevronLeft class="size-5 shrink-0 text-muted transition-colors group-hover:text-accent" />
+				<span class="min-w-0">
+					<span class={labelClass}>Previous</span>
+					<span class={titleClass}>{previousPage.title}</span>
+				</span>
+			</a>
+		{:else}
+			<div class="max-[640px]:hidden" aria-hidden="true"></div>
+		{/if}
+
+		{#if nextPage}
+			<a class={cn(linkClass, 'justify-end text-right')} href={nextPage.route}>
+				<span class="min-w-0">
+					<span class={labelClass}>Next</span>
+					<span class={titleClass}>{nextPage.title}</span>
+				</span>
+				<ChevronRight
+					class="size-5 shrink-0 text-muted transition-colors group-hover:text-accent"
+				/>
+			</a>
+		{:else}
+			<div class="max-[640px]:hidden" aria-hidden="true"></div>
+		{/if}
+	</nav>
+{/if}

package/site/src/lib/components/doc/DocShell.svelte

@@ -0,0 +1,115 @@
+<script lang="ts">
+	import { afterNavigate } from '$app/navigation';
+	import { page } from '$app/state';
+	import Menu from '@lucide/svelte/icons/menu';
+	import { onMount, type Snippet } from 'svelte';
+	import { provideFileWorkspace } from '$lib/components/files/file-workspace.svelte';
+	import type { NavNode } from '$lib/types';
+	import { site } from '$lib/config';
+	import { ThemeToggle } from '$lib/components/ui';
+	import IconButton from '../ui/IconButton.svelte';
+	import { SearchButton, SearchPalette } from '$lib/components/search';
+	import GraphPanel from '$lib/components/graph/GraphPanel.svelte';
+	import DocPager from './DocPager.svelte';
+	import ReaderModeToggle from './ReaderModeToggle.svelte';
+	import Sidebar from './Sidebar.svelte';
+	import Toc from './Toc.svelte';
+	import { readerMode } from './reader-mode.svelte';
+	import { createHeadingTracker } from './heading-tracker.svelte';
+
+	interface Props {
+		nav: NavNode[];
+		children: Snippet;
+	}
+
+	const { nav, children }: Props = $props();
+	const workspace = provideFileWorkspace();
+	onMount(() => workspace.restore());
+
+	let mobileNavOpen = $state(false);
+	let navigationReady = $state(false);
+	type RailPageData = { kind?: string };
+	const railPageData = $derived(page.data as RailPageData);
+	const showContentRail = $derived(railPageData.kind === 'page');
+	const heading = createHeadingTracker(() => page.data.toc ?? []);
+
+	afterNavigate(() => {
+		mobileNavOpen = false;
+		navigationReady = true;
+	});
+</script>
+
+<div
+	class={[
+		'doc-shell min-h-screen',
+		railPageData.kind === 'file-browser' && 'doc-shell-files',
+		!showContentRail && 'doc-shell-listing',
+		readerMode.enabled && 'doc-shell-reader'
+	]}
+>
+	<header
+		class="doc-mobile-header sticky top-0 z-30 items-center gap-3 border-b border-border bg-bg px-4 py-2"
+	>
+		<IconButton
+			class="size-8 rounded-md border border-border bg-transparent text-text"
+			aria-label="Toggle navigation"
+			aria-expanded={mobileNavOpen}
+			disabled={!navigationReady}
+			onclick={() => (mobileNavOpen = !mobileNavOpen)}
+		>
+			<Menu class="size-5" />
+		</IconButton>
+		<a class="font-bold text-text no-underline" href="/">{site.name}</a>
+		<div class="ml-auto flex items-center gap-1">
+			<SearchButton variant="icon" class="size-8" />
+			<ReaderModeToggle class="size-8" />
+			<ThemeToggle class="size-8" />
+		</div>
+	</header>
+
+	<aside class={['doc-sidebar-left border-r border-border bg-bg', mobileNavOpen && 'doc-nav-open']}>
+		<Sidebar {nav} />
+	</aside>
+
+	{#if readerMode.enabled}
+		<!-- floating controls so reader mode can be exited once the rails are gone -->
+		<div
+			class="doc-reader-controls fixed top-3 right-3 z-30 flex items-center gap-1 rounded-lg border border-border bg-bg/90 p-1 backdrop-blur"
+		>
+			<ReaderModeToggle class="size-8" />
+			<ThemeToggle class="size-8" />
+		</div>
+	{/if}
+
+	{#if mobileNavOpen}
+		<button
+			class="doc-nav-backdrop fixed inset-0 z-40 cursor-pointer border-0 bg-black/40"
+			type="button"
+			aria-label="Close navigation"
+			onclick={() => (mobileNavOpen = false)}
+		></button>
+	{/if}
+
+	<main class="doc-main min-w-0" class:doc-main-files={railPageData.kind === 'file-browser'}>
+		<div class={railPageData.kind === 'file-browser' ? 'h-full w-full' : 'mx-auto max-w-3xl'}>
+			{@render children()}
+			<DocPager {nav} />
+		</div>
+	</main>
+
+	{#if !readerMode.enabled && showContentRail}
+		<aside class="doc-sidebar-right" aria-label="Page tools">
+			<div class="doc-sidebar-right-inner">
+				<GraphPanel />
+				{#if (page.data.toc?.length ?? 0) > 0}
+					<details class="doc-compact-outline">
+						<summary class="cursor-pointer text-sm text-muted">On this page</summary>
+						<Toc active={heading.active} />
+					</details>
+				{/if}
+				<div class="doc-toc"><Toc active={heading.active} /></div>
+			</div>
+		</aside>
+	{/if}
+</div>
+<SearchPalette />

package/site/src/lib/components/doc/LicenseNotice.svelte

@@ -0,0 +1,26 @@
+<script lang="ts">
+	import type { ContentLicense } from '$lib/content-license';
+	const { license }: { license: ContentLicense } = $props();
+</script>
+
+<svelte:head><link rel="license" href={license.url} /></svelte:head>
+
+<aside
+	aria-label="Content license"
+	class="border-t border-border py-3 text-xs leading-relaxed text-muted"
+	data-pagefind-ignore
+>
+	<a
+		href={license.source}
+		class="text-muted underline decoration-border underline-offset-2 hover:text-text"
+		>{license.attribution}</a
+	>
+	·
+	<a
+		href={license.url}
+		rel="license"
+		class="text-muted underline decoration-border underline-offset-2 hover:text-text"
+		>{license.name}</a
+	>, unless otherwise noted.
+	{#if license.changes}<p class="m-0 mt-1">{license.changes}</p>{/if}
+</aside>

package/site/src/lib/components/doc/LockedContent.svelte

@@ -0,0 +1,29 @@
+<script lang="ts">
+	import LockKeyhole from '@lucide/svelte/icons/lock-keyhole';
+	import { page } from '$app/state';
+	import { authEnabled } from '$lib/config';
+</script>
+
+<div
+	class="flex items-start gap-3 rounded-md border border-border p-4 text-sm"
+	data-pagefind-ignore
+>
+	<LockKeyhole class="mt-0.5 size-4 shrink-0 text-muted" />
+	<div>
+		<p class="m-0 font-medium">Content locked</p>
+		<p class="mt-1 mb-3 text-muted">
+			{#if authEnabled}
+				The catalog is public. Reading this content requires approved access.
+			{:else}
+				This content is unavailable on this site.
+			{/if}
+		</p>
+		{#if authEnabled}
+			<a
+				data-sveltekit-reload
+				class="text-accent hover:underline"
+				href={`/login?next=${encodeURIComponent(page.url.pathname)}`}>Sign in to read</a
+			>
+		{/if}
+	</div>
+</div>