cantip 0.1.0

package/app/lib/useKeyboardShortcuts.ts

@@ -0,0 +1,149 @@
+import { useEffect } from 'react'
+
+/**
+ * App-wide keyboard shortcuts: single keys (Gmail/GitHub-style — `l`, `w`) and
+ * two-key sequences (Gmail-style `g` then `c`). These live alongside the
+ * existing Cmd/Ctrl chords (Cmd+K search, Cmd+P file-open); those keep their own
+ * listeners and pass straight through this one untouched.
+ *
+ * Why single keys are safe: browsers reserve almost nothing for bare letters as
+ * long as focus isn't in a text field. The handler's first job is to bail when
+ * the user is typing (input/textarea/contenteditable) or when any modifier is
+ * held — that lets Cmd+K et al. fall through and stops shortcuts from firing
+ * mid-typing. Sequences never collide with the browser at all (it has no notion
+ * of "g then c").
+ */
+
+export type ShortcutGroup = 'Дерево' | 'Вкладки' | 'Навигация'
+
+/** A binding the caller wires to behavior, plus the metadata the `?` overlay shows. */
+export type Shortcut = {
+	/** Single key (e.g. 'l') OR a two-key sequence (e.g. ['g', 'c']). Compared case-insensitively. */
+	keys: string | [string, string]
+	/** What it does — shown in the cheatsheet. */
+	label: string
+	/** Cheatsheet section. */
+	group: ShortcutGroup
+	/** Handler. Only invoked when focus is outside text fields and no modifier is held. */
+	run: () => void
+}
+
+/**
+ * A display-only entry for shortcuts owned elsewhere (the existing Cmd+K / Cmd+P
+ * chords, the Shift+Enter row action) so the `?` overlay can list everything in
+ * one place without those handlers being re-registered here.
+ */
+export type ShortcutInfo = {
+	/** Human-readable key hint, e.g. '⌘K', 'Shift+Enter'. */
+	hint: string
+	label: string
+	group: ShortcutGroup
+}
+
+/**
+ * The full cheatsheet, hand-maintained as the single source of truth for what the
+ * `?` overlay shows. Handlers live with their components (Sidebar, TabBar) via
+ * useKeyboardShortcuts; this list just describes every binding in one place,
+ * including the Cmd/Ctrl chords and the Shift+Enter row action owned elsewhere.
+ * Keep in sync when adding a binding.
+ */
+export const ALL_SHORTCUTS: ShortcutInfo[] = [
+	{ hint: '⌘/Ctrl K', label: 'Поиск по содержимому', group: 'Навигация' },
+	{ hint: '?', label: 'Показать список горячих клавиш', group: 'Навигация' },
+	{ hint: '⌘/Ctrl P', label: 'Поиск файла по имени', group: 'Дерево' },
+	{ hint: 'l', label: 'Найти текущую страницу в дереве', group: 'Дерево' },
+	{ hint: 'c', label: 'Свернуть все папки', group: 'Дерево' },
+	{ hint: 'w', label: 'Закрыть текущую вкладку', group: 'Вкладки' },
+	{ hint: 'Shift+Enter', label: 'Файл — открыть в новой вкладке; папку — развернуть рекурсивно', group: 'Дерево' },
+]
+
+/** True when focus is in an editable surface — single-key shortcuts must not fire there. */
+function isTypingTarget(el: EventTarget | null): boolean {
+	if (!(el instanceof HTMLElement)) return false
+	const tag = el.tagName
+	return tag === 'INPUT' || tag === 'TEXTAREA' || el.isContentEditable
+}
+
+/** How long (ms) the first key of a sequence stays "armed" before the buffer clears. */
+const SEQUENCE_WINDOW_MS = 1000
+
+/**
+ * Register the given shortcuts on `window`. Re-registers when `shortcuts`
+ * changes identity, so callers should memoize or accept the (cheap) churn.
+ */
+export function useKeyboardShortcuts(shortcuts: Shortcut[]): void {
+	useEffect(() => {
+		// Split into single-key and sequence bindings, keyed lowercase.
+		const singles = new Map<string, Shortcut>()
+		const sequences = new Map<string, Map<string, Shortcut>>() // firstKey -> (secondKey -> shortcut)
+		for (const s of shortcuts) {
+			if (typeof s.keys === 'string') {
+				singles.set(s.keys.toLowerCase(), s)
+			} else {
+				const [a, b] = s.keys
+				const branch = sequences.get(a.toLowerCase()) ?? new Map()
+				branch.set(b.toLowerCase(), s)
+				sequences.set(a.toLowerCase(), branch)
+			}
+		}
+
+		let pending: string | null = null
+		let timer: ReturnType<typeof setTimeout> | null = null
+		const clearPending = () => {
+			pending = null
+			if (timer) {
+				clearTimeout(timer)
+				timer = null
+			}
+		}
+
+		const onKey = (e: KeyboardEvent) => {
+			// Let Cmd/Ctrl/Alt chords (search, file-open, browser shortcuts) pass through,
+			// and never fire while the user is typing. Checked first, always.
+			if (e.metaKey || e.ctrlKey || e.altKey) {
+				clearPending()
+				return
+			}
+			if (isTypingTarget(e.target)) {
+				clearPending()
+				return
+			}
+
+			const key = e.key.toLowerCase()
+
+			// Resolving the second key of an armed sequence takes priority.
+			if (pending) {
+				const branch = sequences.get(pending)
+				clearPending()
+				const match = branch?.get(key)
+				if (match) {
+					e.preventDefault()
+					match.run()
+					return
+				}
+				// Not a valid continuation — fall through so this key can still be a
+				// single-key shortcut on its own.
+			}
+
+			// Arm a new sequence if this key starts one.
+			if (sequences.has(key)) {
+				pending = key
+				timer = setTimeout(clearPending, SEQUENCE_WINDOW_MS)
+				return
+			}
+
+			// Single-key shortcut.
+			const single = singles.get(key)
+			if (single) {
+				e.preventDefault()
+				single.run()
+			}
+		}
+
+		window.addEventListener('keydown', onKey)
+		return () => {
+			window.removeEventListener('keydown', onKey)
+			clearPending()
+		}
+	}, [shortcuts])
+}

package/app/lib/utils.ts

@@ -0,0 +1,17 @@
+import { clsx, type ClassValue } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]) {
+	return twMerge(clsx(inputs))
+}
+
+// MoSCoW priority tags, in descending priority. Stored alongside type tags
+// (user-story, feature, …) in a doc's `tags` frontmatter array.
+export const PRIORITY_TAGS = ['must-have', 'should-have', 'could-have', 'wont-have'] as const
+export type PriorityTag = (typeof PRIORITY_TAGS)[number]
+
+/** The MoSCoW priority tag from a doc's tags, or null if none is present. */
+export function getPriority(tags: unknown): PriorityTag | null {
+	if (!Array.isArray(tags)) return null
+	return (PRIORITY_TAGS.find((p) => tags.includes(p)) as PriorityTag | undefined) ?? null
+}

package/app/root.tsx

@@ -0,0 +1,171 @@
+import {
+	Links,
+	Meta,
+	Outlet,
+	Scripts,
+	ScrollRestoration,
+	useLoaderData,
+	useLocation,
+} from '@remix-run/react'
+import { useEffect, useState } from 'react'
+import type { LinksFunction, LoaderFunctionArgs } from '@remix-run/node'
+
+import { buildSidebar, flattenSidebar } from '~/lib/sidebar.server'
+import { getActiveProjectId } from '~/lib/projects'
+import { site } from '~/lib/site'
+import Sidebar from '~/components/Sidebar'
+import { TopBar } from '~/lib/slots'
+import TabBar from '~/components/TabBar'
+import MobileBottomBar from '~/components/MobileBottomBar'
+import MobileProjectsPanel from '~/components/MobileProjectsPanel'
+import { ShortcutsHelp } from '~/components/ShortcutsHelp'
+import { TabsProvider } from '~/lib/tabs'
+import { cn } from '~/lib/utils'
+import { themeInitScript } from '~/components/theme-toggle'
+import { sidebarWidthInitScript } from '~/components/Sidebar'
+
+import tailwindStyles from '~/styles/tailwind.css?url'
+import appStyles from '~/styles/app.css?url'
+import katexStyles from 'katex/dist/katex.min.css?url'
+// Generated from docs.config.ts `theme` — loaded LAST so its :root/.dark token
+// overrides win over the defaults declared in tailwind.css.
+import themeStyles from '~/generated/theme.generated.css?url'
+
+export const links: LinksFunction = () => [
+	{ rel: 'stylesheet', href: tailwindStyles },
+	{ rel: 'stylesheet', href: appStyles },
+	{ rel: 'stylesheet', href: themeStyles },
+	{ rel: 'stylesheet', href: katexStyles },
+	{ rel: 'icon', type: 'image/svg+xml', href: site.favicon },
+]
+
+// Root loader runs on every navigation; the active project is derived from the
+// request URL and only that project's sidebar tree is built, so the nav persists
+// across client-side navigations and swaps to match the project being viewed.
+export async function loader({ request }: LoaderFunctionArgs) {
+	const projectId = getActiveProjectId(new URL(request.url).pathname)
+	// No active project (e.g. the home page) → no sidebar tree to build.
+	const sidebar = projectId ? flattenSidebar(await buildSidebar(projectId)) : null
+	return { sidebar, projectId }
+}
+
+export default function App() {
+	const { sidebar, projectId } = useLoaderData<typeof loader>()
+	const location = useLocation()
+	const [menuOpen, setMenuOpen] = useState(false)
+	const [projectsOpen, setProjectsOpen] = useState(false)
+
+	// Close any open mobile overlay whenever navigation happens (link/row click).
+	useEffect(() => {
+		setMenuOpen(false)
+		setProjectsOpen(false)
+	}, [location.pathname])
+
+	return (
+		<html lang={site.lang} className={site.defaultTheme === 'light' ? undefined : 'dark'}>
+			<head>
+				<meta charSet="utf-8" />
+				<meta name="viewport" content="width=device-width, initial-scale=1" />
+				<Meta />
+				<Links />
+				{/* Set the theme class before paint to avoid a flash of the wrong theme. */}
+				<script dangerouslySetInnerHTML={{ __html: themeInitScript }} />
+				{/* Apply the persisted sidebar width before paint to avoid a layout shift. */}
+				<script dangerouslySetInnerHTML={{ __html: sidebarWidthInitScript }} />
+			</head>
+			<body>
+				<TabsProvider projectId={projectId}>
+					{/* Desktop top bar with theme toggle: in-flow at the top (takes layout
+					    space), floats and hides on scroll-down / shows on scroll-up. */}
+					<TopBar projectId={projectId} />
+
+					{/* Two-row grid: row 1 holds the tab bar (over the content columns only),
+					    row 2 holds the doc content + TOC. The sidebar spans both rows so it
+					    stays full-height. When no tabs are open the TabBar renders nothing, so
+					    its 0-height row collapses and the layout matches the no-tabs case.
+					    With no active project (e.g. `/`) there's no sidebar, so the leading
+					    sidebar column is dropped and content starts at the first column. */}
+					<div
+						className={cn(
+							'grid min-h-screen grid-cols-1 grid-rows-[auto_minmax(0,1fr)]',
+							// No sidebar (e.g. `/`): a single full-width content column, no
+							// reserved TOC column — the page has no TOC, so leaving that column
+							// in place would push the centered content left of true center.
+							sidebar
+								? 'md:grid-cols-[var(--sidebar-width)_minmax(0,1fr)] xl:grid-cols-[var(--sidebar-width)_minmax(0,1fr)_var(--toc-width,250px)]'
+								: 'md:grid-cols-[minmax(0,1fr)]',
+						)}
+					>
+						{/* key on projectId: the headless-tree instance caches expanded/registered
+						    items and won't re-sync to a new `data` map on its own, so switching
+						    projects would leave the tree showing stale state. Remounting on
+						    project change rebuilds it cleanly with the new data + initial expand. */}
+						{sidebar && (
+							<Sidebar
+								key={projectId}
+								data={sidebar}
+								currentPath={location.pathname}
+								open={menuOpen}
+								className="md:col-start-1 md:row-span-2 md:row-start-1"
+							/>
+						)}
+						{/* Tab strip: row 1, content column only (col-start-2) — not over the
+						    sidebar (col 1) nor the TOC (col 3 at xl). The grid CELL is the
+						    sticky element (top-11, just below the TopBar): a sticky grid item's
+						    travel range is the whole grid container's box (tall), not its own
+						    row — so it stays pinned while content scrolls. Making the inner
+						    strip sticky instead would fail, since its parent cell is only as
+						    tall as the strip. */}
+						<div
+							className={cn(
+								'sticky top-11 z-40 md:row-start-1',
+								sidebar ? 'md:col-start-2' : 'md:col-start-1',
+							)}
+						>
+							<TabBar />
+						</div>
+						{/* Content lands in row 2, right of the sidebar. The route ($.tsx) emits
+						    <main> + <Toc> as two cells; pinning the wrapper here keeps them in the
+						    content/TOC columns of row 2 regardless of grid auto-placement order. */}
+						<div className="contents md:[&>*]:row-start-2">
+							<Outlet />
+						</div>
+					</div>
+				</TabsProvider>
+
+				{/* Fullscreen mobile project switcher (also houses the theme toggle).
+				    Rendered before the bar so the floating bar stacks above it and its
+				    Projects tab stays tappable to toggle the panel shut. */}
+				<MobileProjectsPanel
+					activeId={projectId}
+					open={projectsOpen}
+					onClose={() => setProjectsOpen(false)}
+				/>
+
+				{/* Mobile-only floating bottom navigation: Home · Проекты · Файлы
+				    (sidebar) · Поиск. No top navbar on mobile. The Files tab is
+				    disabled with no active project (e.g. `/`), where there's no tree. */}
+				<MobileBottomBar
+					dirsOpen={menuOpen}
+					projectsOpen={projectsOpen}
+					filesEnabled={!!projectId}
+					onToggleDirs={() => {
+						setMenuOpen((o) => !o)
+						setProjectsOpen(false)
+					}}
+					onToggleProjects={() => {
+						setProjectsOpen((o) => !o)
+						setMenuOpen(false)
+					}}
+				/>
+
+				{/* `?` cheatsheet for all keyboard shortcuts (single source: ALL_SHORTCUTS).
+				    Owns its own open/close; renders nothing until triggered. */}
+				<ShortcutsHelp />
+
+				<ScrollRestoration />
+				<Scripts />
+			</body>
+		</html>
+	)
+}

package/app/routes/$.tsx

@@ -0,0 +1,158 @@
+import { useEffect } from 'react'
+import { json, redirect } from '@remix-run/node'
+import { useLoaderData, useLocation } from '@remix-run/react'
+import type { LoaderFunctionArgs, MetaFunction } from '@remix-run/node'
+
+import { getDoc, resolvePermalink, getPermalinkForId } from '~/lib/content.server'
+import { getPriority } from '~/lib/utils'
+import { t, pageTitle } from '~/lib/site'
+import { Toc, DocPageOverride } from '~/lib/slots'
+import PageFloatingMenu from '~/components/PageFloatingMenu'
+import CanvasMount from '~/components/CanvasMount'
+import { CodeWrapToggle } from '~/components/CodeWrapToggle'
+
+/** A colored MoSCoW priority pill, rendered inline next to the page title. */
+function PriorityBadge({ priority }: { priority: string }) {
+	return (
+		<span className="priority-badge" data-priority={priority}>
+			{priority}
+		</span>
+	)
+}
+
+/** Render a single frontmatter value as text: arrays comma-joined, everything else stringified. */
+function formatValue(value: unknown): string {
+	if (Array.isArray(value)) return value.map((v) => String(v)).join(', ')
+	if (value === null) return ''
+	if (typeof value === 'object') return JSON.stringify(value)
+	return String(value)
+}
+
+/** A generic key→value table of every frontmatter field, collapsed by default. */
+function FrontmatterTable({ frontmatter }: { frontmatter: Record<string, unknown> }) {
+	const entries = Object.entries(frontmatter)
+	if (entries.length === 0) return null
+	return (
+		<details className="frontmatter">
+			<summary className="frontmatter__summary">{t('properties')}</summary>
+			<dl className="frontmatter__list">
+				{entries.map(([key, value]) => (
+					<div className="frontmatter__row" key={key}>
+						<dt className="frontmatter__key">{key}</dt>
+						<dd className="frontmatter__value">{formatValue(value)}</dd>
+					</div>
+				))}
+			</dl>
+		</details>
+	)
+}
+
+export const loader = async ({ params }: LoaderFunctionArgs) => {
+	// The splat param holds the full doc path, e.g. "krista/глоссарий/коллекция".
+	const slug = (params['*'] ?? '').replace(/\/$/, '')
+
+	// Permalinks make a doc's URL independent of its file name. The permalink is
+	// the canonical URL: if `slug` is a permalink we serve the doc in place; if
+	// it is the file-path URL of a doc that has a permalink, we 301 to the
+	// permalink so there is a single canonical address that survives renames.
+	const permalinkTarget = await resolvePermalink(slug)
+	const docId = permalinkTarget ?? slug
+	if (!permalinkTarget) {
+		const canonical = await getPermalinkForId(slug)
+		if (canonical && canonical !== slug) {
+			return redirect(`/${canonical}/`, 301)
+		}
+	}
+
+	const doc = await getDoc(docId)
+	if (!doc || doc.frontmatter.draft === true) {
+		throw new Response('Not Found', { status: 404 })
+	}
+	const title =
+		(doc.frontmatter.title as string | undefined) ??
+		slug.split('/').pop()?.replace(/-/g, ' ') ??
+		slug
+	return json({ doc, title })
+}
+
+export const meta: MetaFunction<typeof loader> = ({ data }) => {
+	return [{ title: pageTitle(data?.title) }]
+}
+
+/**
+ * Route default export: render the user's `DocPage` override when one is
+ * configured (it receives the same loader data via `useLoaderData`), else the
+ * engine's default doc body below.
+ */
+export default function DocPageRoute() {
+	if (DocPageOverride) return <DocPageOverride />
+	return <EngineDocPage />
+}
+
+function EngineDocPage() {
+	const { doc, title } = useLoaderData<typeof loader>()
+	const showToc = doc.frontmatter.tableOfContents !== false
+	const isCanvas = doc.html.includes('canvas-container')
+	const priority = getPriority(doc.frontmatter.tags)
+
+	// Scroll to the #hash heading after the doc renders. Remix's ScrollRestoration
+	// scrolls to the hash at the navigation's DOM commit, but when navigating
+	// *between* docs the new heading only exists once this component renders the
+	// new HTML — so that initial attempt misses and the first click appears to do
+	// nothing (a second click, now same-doc, works). Re-running keyed on doc.id +
+	// hash covers the cross-doc case. scrollIntoView honours the heading's
+	// scroll-margin-top, so it lands below the sticky bars.
+	const { hash } = useLocation()
+	useEffect(() => {
+		if (!hash) return
+		const id = decodeURIComponent(hash.slice(1))
+		// Wait a frame so the freshly-committed doc HTML is in the DOM.
+		requestAnimationFrame(() => {
+			document.getElementById(id)?.scrollIntoView({ block: 'start', behavior: 'smooth' })
+		})
+	}, [doc.id, hash])
+
+	if (isCanvas) {
+		// Canvas pages span the content + TOC columns (everything right of the sidebar).
+		return (
+			<>
+				<main className="min-w-0 xl:col-span-2">
+					<article className="content">
+						<h1 className="title-row px-10">
+							{title}
+							{priority && <PriorityBadge priority={priority} />}
+						</h1>
+						<div className="px-10">
+							<FrontmatterTable frontmatter={doc.frontmatter} />
+						</div>
+						<div className="body" dangerouslySetInnerHTML={{ __html: doc.html }} />
+					</article>
+				</main>
+				<CanvasMount deps={doc.id} />
+				<CodeWrapToggle deps={doc.id} />
+			</>
+		)
+	}
+
+	return (
+		<>
+			{/* On mobile the bottom padding clears the global bar PLUS the page actions
+			    deck that opens above it (one bar-height row sitting 1.5rem higher), so
+			    the last lines of content never hide behind either, open or closed. */}
+			<main className="mx-auto w-full min-w-0 max-w-[calc(720px+5rem)] px-10 pb-16 pt-8 max-md:px-4 max-md:pb-[calc(2*var(--mobile-bar-height)+env(safe-area-inset-bottom)+3rem)]">
+				<article className="content">
+					<h1 className="title-row">
+						{title}
+						{priority && <PriorityBadge priority={priority} />}
+					</h1>
+					<FrontmatterTable frontmatter={doc.frontmatter} />
+					<div className="body" dangerouslySetInnerHTML={{ __html: doc.html }} />
+				</article>
+			</main>
+			{showToc && <Toc headings={doc.headings} />}
+			{showToc && <PageFloatingMenu headings={doc.headings} />}
+			<CanvasMount deps={doc.id} />
+			<CodeWrapToggle deps={doc.id} />
+		</>
+	)
+}

package/app/routes/_index.tsx

@@ -0,0 +1,60 @@
+import { Link } from '@remix-run/react'
+import type { MetaFunction } from '@remix-run/node'
+
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '~/components/ui/card'
+import { getProjects } from '~/lib/projects'
+import { site } from '~/lib/site'
+import { HomeOverride } from '~/lib/slots'
+
+export const meta: MetaFunction = () => [{ title: site.title }]
+
+const projects = getProjects()
+
+/**
+ * Route default export: render the user's `Home` override when configured, else
+ * the engine's default project-card grid below.
+ */
+export default function IndexRoute() {
+	if (HomeOverride) return <HomeOverride />
+	return <EngineIndex />
+}
+
+function EngineIndex() {
+	return (
+		<main className="mx-auto w-full min-w-0 max-w-[calc(720px+5rem)] px-10 pb-16 pt-8 max-md:px-4 max-md:pb-20">
+			<article className="content">
+				<h1>{site.title}</h1>
+				{site.description && (
+					<p className="mb-8 text-lg text-muted-foreground">{site.description}</p>
+				)}
+
+				<div className="grid grid-cols-[repeat(auto-fit,minmax(280px,1fr))] gap-4">
+					{projects.map((p) => (
+						<Link key={p.id} to={p.landing} className="no-underline">
+							<Card className="h-full gap-3 py-5 transition-colors hover:border-ring">
+								<CardHeader>
+									<div className="flex items-center gap-2.5">
+										{/* Inline size: app.css's unlayered `img{height:auto}` would beat h-* utilities. */}
+										<img
+											src={p.logo}
+											alt=""
+											aria-hidden
+											width={28}
+											height={28}
+											style={{ height: 28, width: 28 }}
+											className="shrink-0 rounded-md"
+										/>
+										<CardTitle className="text-base">{p.name}</CardTitle>
+									</div>
+								</CardHeader>
+								<CardContent>
+									<CardDescription>{p.description}</CardDescription>
+								</CardContent>
+							</Card>
+						</Link>
+					))}
+				</div>
+			</article>
+		</main>
+	)
+}