livemark 0.0.0-dev → 0.7.0

package/build/website/components/SearchDialog.tsx

@@ -2,7 +2,7 @@ import { useState, useRef, useCallback, useMemo } from "react"
 import { useNavigate } from "@tanstack/react-router"
 import { FileText } from "lucide-react"
 import { create, insertMultiple, search } from "@orama/orama"
-import { sortedArticles } from "../helpers/articles.ts"
+import { sortedArticles } from "../content/article.ts"
 import { articleIcons } from "../helpers/article-icon.ts"
 import {
   CommandDialog,
@@ -15,7 +15,7 @@ import {
 
 interface SearchResult {
   title: string
-  pathname: string
+  path: string
   icon: string
   snippet: string
   group: string
@@ -55,12 +55,12 @@ export function SearchDialog(props: {
   const toResult = useCallback(
     (article: (typeof sortedArticles)[number], term: string): SearchResult => ({
       title: article.title,
-      pathname: article.pathname,
+      path: article.path,
       icon: article.icon,
       snippet: term
         ? extractSnippet(article.searchText, term)
         : (article.description ?? ""),
-      group: groupFor(article.pathname),
+      group: groupFor(article.path),
     }),
     [],
   )
@@ -89,7 +89,7 @@ export function SearchDialog(props: {
               {
                 ...sortedArticles[0],
                 title: hit.document.title,
-                pathname: "",
+                path: "",
                 searchText: hit.document.description,
                 description: hit.document.description,
                 icon: "",
@@ -104,13 +104,13 @@ export function SearchDialog(props: {
   )
 
   const handleSelect = useCallback(
-    (pathname: string) => {
+    (path: string) => {
       props.onOpenChange(false)
       setQuery("")
       setResults([])
       navigate({
         to: "/$",
-        params: { _splat: pathname.replace(/^\/|\/$/g, "") },
+        params: { _splat: path.replace(/^\/|\/$/g, "") },
       })
     },
     [navigate, props.onOpenChange],
@@ -153,9 +153,9 @@ export function SearchDialog(props: {
               const Icon = articleIcons[result.icon] ?? FileText
               return (
                 <CommandItem
-                  key={result.pathname}
-                  value={result.pathname}
-                  onSelect={() => handleSelect(result.pathname)}
+                  key={result.path}
+                  value={result.path}
+                  onSelect={() => handleSelect(result.path)}
                   className="py-2.5"
                 >
                   <Icon className="size-5 shrink-0 mt-0.5 self-start opacity-60" />

package/build/website/components/Sidebar.tsx

@@ -0,0 +1,160 @@
+import { Link, useLocation } from "@tanstack/react-router"
+import { useHotkey } from "@tanstack/react-hotkeys"
+import { ChevronRight, FileText } from "lucide-react"
+import {
+  articleGroups,
+  currentSection,
+  sectionArticleGroups,
+} from "../content/article.ts"
+import { articleIcons } from "../helpers/article-icon.ts"
+import type { ArticleNode } from "../models/article.ts"
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from "../elements/collapsible.tsx"
+import {
+  Sidebar as SidebarRoot,
+  SidebarContent,
+  SidebarFooter,
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+  SidebarHeader,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarMenuSub,
+  SidebarMenuSubButton,
+  SidebarMenuSubItem,
+  SidebarRail,
+  useSidebar,
+} from "../elements/sidebar.tsx"
+import { Search } from "./Search.tsx"
+import { SidebarLinks } from "./SidebarLinks.tsx"
+import { SidebarSections } from "./SidebarSections.tsx"
+import { SiteTitle } from "./SiteTitle.tsx"
+import { Theme } from "./Theme.tsx"
+
+/** Application sidebar with article navigation, search, and theme toggle */
+export function Sidebar() {
+  const pathname = useLocation({ select: l => l.pathname })
+  const { toggleSidebar } = useSidebar()
+
+  useHotkey("S", toggleSidebar)
+
+  const configSections = import.meta.env.CONFIG.sections
+  const section = currentSection(`/${pathname.replace(/^\/|\/$/g, "")}/`)
+  const groups = configSections?.length
+    ? (sectionArticleGroups.get(section?.prefix ?? "__default__") ??
+      articleGroups)
+    : articleGroups
+
+  return (
+    <SidebarRoot>
+      <SidebarHeader>
+        <SidebarMenu>
+          <SidebarMenuItem>
+            <SidebarMenuButton size="lg" render={<Link to="/" />}>
+              <SiteTitle />
+            </SidebarMenuButton>
+          </SidebarMenuItem>
+        </SidebarMenu>
+      </SidebarHeader>
+      <SidebarContent>
+        <SidebarSections />
+        {groups.map((group, index) => (
+          <SidebarGroup key={group.name ?? `__unnamed-${index}`}>
+            {group.name && (
+              <SidebarGroupLabel className="uppercase font-mono text-xs tracking-widest">
+                {group.name}
+              </SidebarGroupLabel>
+            )}
+            <SidebarGroupContent>
+              <SidebarMenu>
+                {group.nodes.map(node => (
+                  <NavNode key={node.path} node={node} currentPath={pathname} />
+                ))}
+              </SidebarMenu>
+            </SidebarGroupContent>
+          </SidebarGroup>
+        ))}
+        <SidebarLinks />
+      </SidebarContent>
+      <SidebarFooter className="p-4 space-y-2">
+        <Search />
+        <Theme />
+      </SidebarFooter>
+      <SidebarRail />
+    </SidebarRoot>
+  )
+}
+
+function splatFor(pathname: string) {
+  return { _splat: pathname.replace(/^\/|\/$/g, "") }
+}
+
+function isActive(articlePathname: string, currentPath: string) {
+  const normalized = `/${currentPath.replace(/^\/|\/$/g, "")}/`
+  return articlePathname === normalized
+}
+
+function NavNode(props: { node: ArticleNode; currentPath: string }) {
+  const { node, currentPath } = props
+  const Icon = articleIcons[node.icon] ?? FileText
+  const active = isActive(node.path, currentPath)
+
+  if (node.children.length === 0) {
+    return (
+      <SidebarMenuItem>
+        <SidebarMenuButton
+          isActive={active}
+          className={active ? "" : "opacity-75"}
+          render={<Link to="/$" params={splatFor(node.path)} />}
+        >
+          <Icon className="size-4" />
+          <span>{node.label ?? node.title}</span>
+        </SidebarMenuButton>
+      </SidebarMenuItem>
+    )
+  }
+
+  return (
+    <SidebarMenuItem>
+      <Collapsible defaultOpen className="group/collapsible">
+        <SidebarMenuButton
+          isActive={active}
+          className={active ? "" : "opacity-75"}
+          render={<Link to="/$" params={splatFor(node.path)} />}
+        >
+          <Icon className="size-4" />
+          <span>{node.label ?? node.title}</span>
+        </SidebarMenuButton>
+        <CollapsibleTrigger
+          aria-label={`Toggle ${node.label ?? node.title} submenu`}
+          className="absolute right-1 top-1.5 p-1 rounded-md hover:bg-sidebar-accent"
+        >
+          <ChevronRight className="size-3.5 transition-transform group-data-[open]/collapsible:rotate-90" />
+        </CollapsibleTrigger>
+        <CollapsibleContent>
+          <SidebarMenuSub>
+            {node.children.map(child => {
+              const childIsActive = isActive(child.path, currentPath)
+              return (
+                <SidebarMenuSubItem key={child.path}>
+                  <SidebarMenuSubButton
+                    isActive={childIsActive}
+                    className={childIsActive ? "" : "opacity-75"}
+                    render={<Link to="/$" params={splatFor(child.path)} />}
+                  >
+                    <span>{child.label ?? child.title}</span>
+                  </SidebarMenuSubButton>
+                </SidebarMenuSubItem>
+              )
+            })}
+          </SidebarMenuSub>
+        </CollapsibleContent>
+      </Collapsible>
+    </SidebarMenuItem>
+  )
+}

package/build/website/components/SidebarLinks.tsx

@@ -0,0 +1,70 @@
+import { useLocation } from "@tanstack/react-router"
+import { ExternalLink } from "lucide-react"
+import { currentSection } from "../content/article.ts"
+import { DynamicIcon } from "../helpers/dynamic-icon.tsx"
+import {
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+} from "../elements/sidebar.tsx"
+
+/** Shared Links group. Renders sidebar-positioned links always, and
+ * header-positioned links only on mobile (mobile collapses all chrome
+ * links into the sidebar since the header strip is hidden below `md`). */
+export function SidebarLinks() {
+  const pathname = useLocation({ select: l => l.pathname })
+  const section = currentSection(`/${pathname.replace(/^\/|\/$/g, "")}/`)
+  const links =
+    import.meta.env.CONFIG.links?.filter(
+      link => !link.prefix || link.prefix === section?.prefix,
+    ) ?? []
+
+  if (!links.length) return null
+  const hasDesktopItems = links.some(l => l.position === "sidebar")
+
+  return (
+    <SidebarGroup className={hasDesktopItems ? undefined : "md:hidden"}>
+      <SidebarGroupLabel className="uppercase font-mono text-xs tracking-widest">
+        Links
+      </SidebarGroupLabel>
+      <SidebarGroupContent>
+        <SidebarMenu>
+          {links.map(link => {
+            const mobileOnly = link.position !== "sidebar"
+            return (
+              <SidebarMenuItem
+                key={link.url}
+                className={mobileOnly ? "md:hidden" : undefined}
+              >
+                <SidebarMenuButton
+                  className="text-muted-foreground"
+                  render={
+                    <a
+                      href={link.url}
+                      target="_blank"
+                      rel="noopener noreferrer"
+                    />
+                  }
+                >
+                  {link.icon && (
+                    <DynamicIcon name={link.icon} className="size-4" />
+                  )}
+                  <span>
+                    {link.title}{" "}
+                    <ExternalLink
+                      className="inline -mt-0.5 opacity-75"
+                      style={{ width: 12, height: 12 }}
+                    />
+                  </span>
+                </SidebarMenuButton>
+              </SidebarMenuItem>
+            )
+          })}
+        </SidebarMenu>
+      </SidebarGroupContent>
+    </SidebarGroup>
+  )
+}

package/build/website/components/SidebarSections.tsx

@@ -0,0 +1,71 @@
+import { Link, useLocation, useMatch } from "@tanstack/react-router"
+import { currentSection, sectionFirstArticle } from "../content/article.ts"
+import { DynamicIcon } from "../helpers/dynamic-icon.tsx"
+import { sectionIcon } from "../helpers/section.ts"
+import {
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+  SidebarMenu,
+  SidebarMenuButton,
+  SidebarMenuItem,
+} from "../elements/sidebar.tsx"
+
+function splatFor(pathname: string) {
+  return { _splat: pathname.replace(/^\/|\/$/g, "") }
+}
+
+/** Shared Sections group. Renders sidebar-positioned sections always, and
+ * header-positioned sections only on mobile (mobile collapses all sections
+ * into the sidebar since the header nav strip is hidden below `md`). */
+export function SidebarSections() {
+  const pathname = useLocation({ select: l => l.pathname })
+  const articleRoute = useMatch({ from: "/$", shouldThrow: false })
+  const section = articleRoute
+    ? currentSection(`/${pathname.replace(/^\/|\/$/g, "")}/`)
+    : undefined
+  const sections = import.meta.env.CONFIG.sections ?? []
+
+  if (!sections.length) return null
+  const hasDesktopItems = sections.some(s => s.position === "sidebar")
+
+  return (
+    <SidebarGroup className={hasDesktopItems ? undefined : "md:hidden"}>
+      <SidebarGroupLabel className="uppercase font-mono text-xs tracking-widest">
+        Sections
+      </SidebarGroupLabel>
+      <SidebarGroupContent>
+        <SidebarMenu>
+          {sections.map(s => {
+            const target =
+              s.type === "blog" || s.type === "changelog"
+                ? s.prefix
+                : (sectionFirstArticle.get(s.prefix) ?? s.prefix)
+            const active = section?.prefix === s.prefix
+            const mobileOnly = s.position !== "sidebar"
+            return (
+              <SidebarMenuItem
+                key={s.prefix}
+                className={mobileOnly ? "md:hidden" : undefined}
+              >
+                <SidebarMenuButton
+                  isActive={active}
+                  className={active ? "" : "opacity-75"}
+                  render={
+                    <Link
+                      to={target === "/" ? "/" : "/$"}
+                      params={target && target !== "/" ? splatFor(target) : {}}
+                    />
+                  }
+                >
+                  <DynamicIcon name={sectionIcon(s)} className="size-4" />
+                  <span>{s.title}</span>
+                </SidebarMenuButton>
+              </SidebarMenuItem>
+            )
+          })}
+        </SidebarMenu>
+      </SidebarGroupContent>
+    </SidebarGroup>
+  )
+}

package/build/website/components/SiteTitle.tsx

@@ -1,16 +1,21 @@
-/** Renders the site title and description in the sidebar header */
+import defaultLogo from "../assets/logo.svg"
+
+/** Renders the site logo, title, and description in the sidebar header */
 export function SiteTitle() {
+  const logo = import.meta.env.CONFIG.logo ?? defaultLogo
   return (
-    <>
+    <div className="flex items-end gap-2.5 text-sm">
       <img
-        src="/logo.svg"
-        alt={import.meta.env.SITE_TITLE}
-        className="size-8 rounded-lg"
+        src={logo}
+        alt={import.meta.env.CONFIG.title}
+        className="size-6.5 mb-1.25"
       />
       <div className="flex flex-col gap-0.5 leading-none">
-        <span className="font-semibold">{import.meta.env.SITE_TITLE}</span>
-        <span className="text-xs">{import.meta.env.SITE_DESCRIPTION}</span>
+        <span className="font-semibold">{import.meta.env.CONFIG.title}</span>
+        <span className="text-xs opacity-80">
+          {import.meta.env.CONFIG.description}
+        </span>
       </div>
-    </>
+    </div>
   )
 }

package/build/website/components/TagIndex.tsx

@@ -0,0 +1,120 @@
+import { Link } from "@tanstack/react-router"
+import { History } from "lucide-react"
+import { sortedArticles } from "../content/article.ts"
+import { sectionTags } from "../content/tag.ts"
+import { Separator } from "../elements/separator.tsx"
+import { TocContext } from "../helpers/toc-context.ts"
+import { Footer } from "./Footer.tsx"
+import { PageToolbar } from "./PageToolbar.tsx"
+import { MobileToc, Toc } from "./Toc.tsx"
+
+/** Blog tag page listing posts filtered by a specific tag */
+export function TagIndex(props: { sectionPrefix: string; tag: string }) {
+  const tagMap = sectionTags.get(props.sectionPrefix)
+  const paths = tagMap?.get(props.tag) ?? []
+  const posts = paths
+    .map(p => sortedArticles.find(a => a.path === p))
+    .filter(a => a !== undefined)
+
+  const tocItems = posts.map(post => ({
+    url: `#${slugOf(post.path)}`,
+    title: post.title,
+    depth: 2,
+  }))
+
+  const title = `Posts tagged '${props.tag}'`
+
+  const content = [
+    `# ${title}`,
+    ...posts.map(post => {
+      const parts = [`## ${post.title}`]
+      if (post.date) parts.push(formatDate(post.date))
+      if (post.author) {
+        parts.push(
+          Array.isArray(post.author) ? post.author.join(", ") : post.author,
+        )
+      }
+      if (post.description) parts.push("", post.description)
+      return parts.join("\n")
+    }),
+  ].join("\n\n")
+
+  return (
+    <TocContext.Provider value={tocItems}>
+      <MobileToc items={tocItems}>
+        <PageToolbar content={content} />
+      </MobileToc>
+      <div className="flex flex-1 gap-10 p-4 pt-8 md:p-10">
+        <div className="flex-1 min-w-0 mx-auto max-w-3xl">
+          <div className="prose dark:prose-invert max-w-none mb-8">
+            <h1 id="top">
+              <a href="#top">Posts tagged &lsquo;{props.tag}&rsquo;</a>
+            </h1>
+            {posts[0]?.date && (
+              <p className="flex flex-wrap items-center gap-x-3 gap-y-1 text-sm text-muted-foreground !-mt-4 !mb-0">
+                <span className="flex items-center gap-1.5">
+                  <History className="size-3.5" />
+                  Updated {formatDate(posts[0].date)}
+                </span>
+              </p>
+            )}
+          </div>
+          <div className="space-y-6">
+            {posts.map((post, i) => (
+              <article key={post.path} id={slugOf(post.path)}>
+                {i > 0 && <Separator className="mb-6" />}
+                <h2 className="text-2xl">
+                  <Link
+                    to="/$"
+                    params={{ _splat: post.path.replace(/^\/|\/$/g, "") }}
+                    className="font-medium hover:text-primary transition-colors"
+                  >
+                    {post.title}
+                  </Link>
+                </h2>
+                <p className="text-sm text-muted-foreground mt-1 flex gap-3">
+                  {post.date && <span>{formatDate(post.date)}</span>}
+                  {post.author && (
+                    <span>
+                      {Array.isArray(post.author)
+                        ? post.author.join(", ")
+                        : post.author}
+                    </span>
+                  )}
+                </p>
+                {post.description && (
+                  <p className="text-muted-foreground mt-2">
+                    {post.description}
+                  </p>
+                )}
+              </article>
+            ))}
+          </div>
+          <div className="mt-10">
+            <Footer />
+          </div>
+        </div>
+        <Toc items={tocItems}>
+          <PageToolbar content={content} />
+        </Toc>
+      </div>
+    </TocContext.Provider>
+  )
+}
+
+function slugOf(path: string) {
+  return (
+    path
+      .replace(/^\/|\/$/g, "")
+      .split("/")
+      .pop() ?? ""
+  )
+}
+
+function formatDate(iso: string) {
+  return new Date(iso).toLocaleDateString("en-US", {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+  })
+}

package/build/website/components/Theme.tsx

@@ -18,7 +18,6 @@ export function Theme() {
       size="sm"
       onClick={handleToggle}
       title="Change Theme"
-      aria-label="Toggle color scheme"
       className="w-full h-auto rounded-xl cursor-pointer text-xs font-normal justify-start text-muted-foreground bg-sidebar-accent/70 border border-border shadow-xs hover:!bg-background px-3 py-2"
     >
       <div className="flex flex-1 gap-2 items-center dark:hidden">

package/build/website/components/Toc.tsx

@@ -1,5 +1,6 @@
+import { ChevronDown } from "lucide-react"
 import { useEffect, useRef, useState, type ReactNode } from "react"
-import type { TocItem } from "../helpers/toc.ts"
+import type { TocItem } from "../models/toc.ts"
 
 export function Toc(props: { items: TocItem[]; children?: ReactNode }) {
   const activeId = useActiveHeading(props.items)
@@ -33,6 +34,132 @@ export function Toc(props: { items: TocItem[]; children?: ReactNode }) {
   )
 }
 
+/** Mobile-only sticky secondary bar showing the active heading and an
+ * overlay dropdown with the Contents + page Actions. */
+export function MobileToc(props: { items: TocItem[]; children?: ReactNode }) {
+  const activeId = useActiveHeading(props.items)
+  const [open, setOpen] = useState(false)
+  const wrapperRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    if (!open) return
+    const onPointerDown = (event: MouseEvent) => {
+      if (!wrapperRef.current?.contains(event.target as Node)) setOpen(false)
+    }
+    const onKey = (event: KeyboardEvent) => {
+      if (event.key === "Escape") setOpen(false)
+    }
+    document.addEventListener("mousedown", onPointerDown)
+    document.addEventListener("keydown", onKey)
+    return () => {
+      document.removeEventListener("mousedown", onPointerDown)
+      document.removeEventListener("keydown", onKey)
+    }
+  }, [open])
+
+  if (props.items.length === 0 && !props.children) return null
+
+  const active = props.items.find(item => item.url.slice(1) === activeId)
+  const title = active?.title ?? props.items[0]?.title ?? "Contents"
+
+  return (
+    <div
+      ref={wrapperRef}
+      className="xl:hidden sticky top-16 z-20 border-b bg-background"
+    >
+      <button
+        type="button"
+        onClick={() => setOpen(v => !v)}
+        aria-expanded={open}
+        className="flex w-full items-center gap-3 px-4 py-3 text-sm text-muted-foreground"
+      >
+        <ScrollProgressRing />
+        <span className="truncate flex-1 text-left">{title}</span>
+        <ChevronDown
+          className={`size-4 shrink-0 transition-transform ${open ? "rotate-180" : ""}`}
+        />
+      </button>
+      {open && (
+        <div className="absolute top-full left-0 right-0 mt-px max-h-[calc(100vh-8rem)] overflow-auto border-b bg-background shadow-md animate-in slide-in-from-top-2 fade-in-0 duration-200">
+          <div className="space-y-4 px-4 pt-4 pb-4">
+            {props.children}
+            {props.items.length > 0 && (
+              <nav>
+                <p className="mb-2 text-sm font-medium">Contents</p>
+                <ul className="border-l border-border text-sm">
+                  {props.items.map(item => (
+                    <li key={item.url}>
+                      <a
+                        href={item.url}
+                        data-active={
+                          activeId === item.url.slice(1) || undefined
+                        }
+                        onClick={() => setOpen(false)}
+                        className={`-ms-px block border-l border-transparent py-1.5 text-muted-foreground transition-colors hover:text-foreground data-[active]:border-primary data-[active]:font-medium data-[active]:text-primary ${item.depth <= 2 ? "ps-3" : item.depth === 3 ? "ps-6" : "ps-8"}`}
+                      >
+                        {item.title}
+                      </a>
+                    </li>
+                  ))}
+                </ul>
+              </nav>
+            )}
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}
+
+function ScrollProgressRing() {
+  const progress = useScrollProgress()
+  const radius = 6
+  const circumference = 2 * Math.PI * radius
+  const offset = circumference * (1 - progress)
+  return (
+    <svg viewBox="0 0 16 16" className="size-4 shrink-0 -rotate-90" aria-hidden>
+      <circle
+        cx="8"
+        cy="8"
+        r={radius}
+        className="stroke-muted-foreground/30"
+        strokeWidth="2"
+        fill="none"
+      />
+      <circle
+        cx="8"
+        cy="8"
+        r={radius}
+        className="stroke-primary transition-[stroke-dashoffset] duration-150"
+        strokeWidth="2"
+        fill="none"
+        strokeLinecap="round"
+        strokeDasharray={circumference}
+        strokeDashoffset={offset}
+      />
+    </svg>
+  )
+}
+
+function useScrollProgress() {
+  const [progress, setProgress] = useState(0)
+  useEffect(() => {
+    const update = () => {
+      const max = document.documentElement.scrollHeight - window.innerHeight
+      const next = max > 0 ? window.scrollY / max : 0
+      setProgress(Math.min(1, Math.max(0, next)))
+    }
+    update()
+    window.addEventListener("scroll", update, { passive: true })
+    window.addEventListener("resize", update)
+    return () => {
+      window.removeEventListener("scroll", update)
+      window.removeEventListener("resize", update)
+    }
+  }, [])
+  return progress
+}
+
 function useActiveHeading(items: TocItem[]) {
   const [activeId, setActiveId] = useState<string>("")
   const observer = useRef<IntersectionObserver | null>(null)