Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
// oxlint-disable ok/no-raw-error-toast -- pre-rule backlog: toasts here show raw error text; delete this line once the file maps each failure to written copy. See https://github.com/inkeep/open-knowledge/blob/main/lint-plugins/ok-rules/README.md#no-raw-error-toast
// oxlint-disable ok/no-raw-html-interactive-element -- pre-rule backlog — file uses raw <button>/<input>/<textarea> awaiting shadcn migration; tracked at https://github.com/inkeep/open-knowledge/blob/main/lint-plugins/ok-rules/README.md#no-raw-html-interactive-element
// oxlint-disable ok/no-physical-direction-utility -- pre-rule backlog — physical margin/padding/inset utilities predate the rule; drain by swapping ml/mr → ms/me, pl/pr → ps/pe, left/right → start/end, then deleting this line. See https://github.com/inkeep/open-knowledge/blob/main/lint-plugins/ok-rules/README.md#no-physical-direction-utility
import {
type BacklinkEntry,
BacklinksSuccessSchema,
type ForwardLinkEntry,
type ForwardLinkLocalTarget,
type ForwardLinksSuccess,
ForwardLinksSuccessSchema,
ProblemDetailsSchema,
} from '@inkeep/open-knowledge-core/schemas/api';
import { t } from '@lingui/core/macro';
import { Trans, useLingui } from '@lingui/react/macro';
import { useQuery } from '@tanstack/react-query';
import {
ArrowUpRight,
ChevronDown,
ChevronRight,
File,
Folder,
Image as ImageIcon,
TriangleAlert,
} from 'lucide-react';
import type { ReactNode } from 'react';
import { useState } from 'react';
import { toast } from 'sonner';
import { resolveLinkTargetIntent } from '@/components/link-target-intent';
import { usePageList } from '@/components/PageListContext';
import { LINT_NAV_EVENT, type LintNavDetail } from '@/components/ProblemsPanel';
import { isKnownPageDocName } from '@/components/page-membership';
import { Badge } from '@/components/ui/badge';
import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '@/components/ui/collapsible';
import {
Panel,
PanelBody,
PanelCount,
PanelEmpty,
PanelError,
PanelTitle,
} from '@/components/ui/panel';
import { Separator } from '@/components/ui/separator';
import { Tooltip, TooltipContent, TooltipTrigger } from '@/components/ui/tooltip';
import { HttpResponseParseError } from '@/editor/http-client';
import { rememberPendingSourceNavigation } from '@/editor/source-editor-navigation';
import { type CreatePageSeed, createPageFromSeedAndUpdate } from '@/lib/create-page';
import { hashFromDocName } from '@/lib/doc-hash';
import { cn } from '@/lib/utils';
import { resolveTargetNavigationIntent } from './target-navigation-intent';
const INITIAL_VISIBLE = 5;
async function fetchBacklinks(docName: string): Promise<BacklinkEntry[]> {
const res = await fetch(`/api/backlinks?docName=${encodeURIComponent(docName)}`);
const body = (await res.json().catch(() => null)) as unknown;
if (!res.ok) {
const problem = ProblemDetailsSchema.safeParse(body);
const status = res.status;
if (!problem.success) {
throw new HttpResponseParseError(
t`Failed to parse backlinks error response (HTTP ${status})`,
{ status },
);
}
throw new Error(problem.data.title);
}
const success = BacklinksSuccessSchema.safeParse(body);
if (!success.success) {
throw new HttpResponseParseError(t`Backlinks response did not match expected shape.`, {
status: res.status,
});
}
return success.data.backlinks;
}
async function fetchForwardLinks(docName: string): Promise<ForwardLinksSuccess> {
const res = await fetch(`/api/forward-links?docName=${encodeURIComponent(docName)}`);
const body = (await res.json().catch(() => null)) as unknown;
if (!res.ok) {
const problem = ProblemDetailsSchema.safeParse(body);
const status = res.status;
if (!problem.success) {
throw new HttpResponseParseError(
t`Failed to parse forward-links error response (HTTP ${status})`,
{ status },
);
}
throw new Error(problem.data.title);
}
const success = ForwardLinksSuccessSchema.safeParse(body);
if (!success.success) {
throw new HttpResponseParseError(t`Forward-links response did not match expected shape.`, {
status: res.status,
});
}
return success.data;
}
function compactDocPath(docName: string): string {
const segments = docName.split('/');
if (segments.length <= 2) return docName;
return `…/${segments.slice(-2).join('/')}`;
}
function navigateToDocHash(docName: string): void {
window.location.hash = hashFromDocName(docName);
}
function SectionTrigger({
title,
count,
isLoading,
}: {
title: string;
count: number | null;
isLoading: boolean;
}) {
return (
<CollapsibleTrigger className="group flex w-full cursor-pointer items-center px-5 py-3 text-left transition-colors hover:bg-muted/40">
<span className="flex items-center gap-2.5">
<ChevronDown className="size-3.5 text-muted-foreground transition-transform group-data-[state=closed]:-rotate-90" />
<PanelTitle>{title}</PanelTitle>
{!isLoading && count !== null && <PanelCount>{count}</PanelCount>}
</span>
</CollapsibleTrigger>
);
}
function ShowMoreButton({
total,
expanded,
onToggle,
}: {
total: number;
expanded: boolean;
onToggle: () => void;
}) {
if (total <= INITIAL_VISIBLE) return null;
const hidden = total - INITIAL_VISIBLE;
return (
<button
type="button"
aria-expanded={expanded}
className="mt-2 inline-flex cursor-pointer items-center gap-1 px-3 text-xs text-muted-foreground transition-colors hover:text-foreground"
onClick={onToggle}
>
{expanded ? <ChevronDown className="size-3" /> : <ChevronRight className="size-3" />}
{expanded ? <Trans>Show fewer</Trans> : <Trans>Show {hidden} more</Trans>}
</button>
);
}
interface LinkRowProps {
icon: ReactNode;
iconColorClass?: string;
rowTooltip?: string;
title: string;
path?: string;
anchor?: string | null;
snippet?: string | null;
titleHover?: string;
ariaLabel?: string;
href?: string;
external?: boolean;
disabled?: boolean;
onClick?: () => void;
trailing?: ReactNode;
}
function LinkRow({
icon,
iconColorClass,
rowTooltip,
title,
path,
anchor,
snippet,
titleHover,
ariaLabel,
href,
external,
disabled,
onClick,
trailing,
}: LinkRowProps) {
const showPath = path !== undefined && path !== title;
const iconNode = (
<span className={cn('mt-0.5 shrink-0', iconColorClass ?? 'text-muted-foreground')}>{icon}</span>
);
const overlayClassName =
'block w-full truncate text-left font-medium text-foreground no-underline outline-none after:absolute after:inset-0 after:rounded-md focus-visible:after:ring-2 focus-visible:after:ring-ring';
const primaryInteractive = href ? (
<a
href={href}
target={external ? '_blank' : undefined}
rel={external ? 'noopener noreferrer' : undefined}
aria-label={ariaLabel}
title={titleHover}
onClick={onClick}
className={overlayClassName}
>
{title}
{external ? (
<span className="sr-only">
{' '}
<Trans>(opens in new tab)</Trans>
</span>
) : null}
</a>
) : (
<button
type="button"
aria-label={ariaLabel}
title={titleHover}
disabled={disabled}
onClick={onClick}
className={cn(
overlayClassName,
'cursor-pointer bg-transparent p-0 disabled:cursor-not-allowed disabled:opacity-60',
)}
>
{title}
</button>
);
const row = (
<div className="group relative flex items-start gap-2.5 rounded-md px-3 py-2.5 transition-colors hover:bg-muted/80">
<div className="mt-px flex items-center">{iconNode}</div>
<div className="min-w-0 flex-1 space-y-0.5 text-1sm">
{primaryInteractive}
{showPath ? (
<div className="truncate font-mono text-xs text-muted-foreground">
{path}
{anchor ? <span className="ml-1">· #{anchor}</span> : null}
</div>
) : null}
{snippet ? <p className="line-clamp-2 text-muted-foreground">{snippet}</p> : null}
</div>
{trailing ? <div className="mt-0.5 flex shrink-0 items-center">{trailing}</div> : null}
</div>
);
if (rowTooltip) {
return (
<Tooltip>
<TooltipTrigger asChild>{row}</TooltipTrigger>
<TooltipContent side="top">{rowTooltip}</TooltipContent>
</Tooltip>
);
}
return row;
}
function BacklinksSection({
docName,
onDestinationRequested,
}: {
docName: string;
onDestinationRequested?: (docName: string) => void;
}) {
const { t } = useLingui();
const {
folderPaths,
pages,
pagesBySlug,
pagesByBasename,
loading,
error: pageListError,
} = usePageList();
const { data, isLoading, error } = useQuery({
queryKey: ['backlinks', docName],
queryFn: () => fetchBacklinks(docName),
enabled: !loading && isKnownPageDocName(pages, docName),
});
const backlinks = data ?? [];
const isUnresolvable =
!loading && pageListError === null && !isKnownPageDocName(pages, docName) && data !== undefined;
const [expanded, setExpanded] = useState(false);
const [prevDocName, setPrevDocName] = useState(docName);
if (prevDocName !== docName) {
setPrevDocName(docName);
setExpanded(false);
}
const visible = expanded ? backlinks : backlinks.slice(0, INITIAL_VISIBLE);
return (
<Collapsible defaultOpen>
<SectionTrigger
title={t`Backlinks`}
count={error !== null || isUnresolvable ? null : backlinks.length}
isLoading={isLoading}
/>
<CollapsibleContent>
<div className="px-2 pb-3" aria-busy={isLoading}>
{isUnresolvable ? (
<div className="px-3">
<PanelEmpty role="status">
<Trans>This page is no longer at this path.</Trans>
</PanelEmpty>
</div>
) : error ? (
<div className="px-3">
<PanelError>
{error instanceof Error ? error.message : t`Failed to load backlinks`}
</PanelError>
</div>
) : backlinks.length === 0 && !isLoading ? (
<div className="px-3">
<PanelEmpty>
<Trans>No pages link here yet.</Trans>
</PanelEmpty>
</div>
) : (
<>
<div className="flex flex-col gap-1">
{visible.map((backlink, index) => {
const navigationIntent = resolveTargetNavigationIntent(backlink.source, {
pages,
folderPaths,
pagesBySlug,
pagesByBasename,
});
return (
<LinkRow
// biome-ignore lint/suspicious/noArrayIndexKey: rows are stable per poll; source may repeat if API adds multiple edges per source
key={`${backlink.source}-${index}`}
icon={<File className="size-3.5" />}
title={backlink.title}
path={compactDocPath(backlink.source)}
titleHover={backlink.source}
anchor={backlink.anchor}
snippet={backlink.snippet}
href={hashFromDocName(navigationIntent.hashDocName, backlink.anchor)}
onClick={() => onDestinationRequested?.(navigationIntent.hashDocName)}
/>
);
})}
</div>
<ShowMoreButton
total={backlinks.length}
expanded={expanded}
onToggle={() => setExpanded((prev) => !prev)}
/>
</>
)}
</div>
</CollapsibleContent>
</Collapsible>
);
}
function ForwardLinksSection({
docName,
onDestinationRequested,
}: {
docName: string;
onDestinationRequested?: (docName: string) => void;
}) {
const { t } = useLingui();
const {
addPage,
folderPaths,
pages,
pagesBySlug,
pagesByBasename,
loading: pagesLoading,
error: pageListError,
} = usePageList();
const { data, isLoading, error } = useQuery({
queryKey: ['forward-links', docName],
queryFn: () => fetchForwardLinks(docName),
enabled: !pagesLoading && isKnownPageDocName(pages, docName),
});
const links = data?.forwardLinks ?? [];
const isUnresolvable =
!pagesLoading &&
pageListError === null &&
!isKnownPageDocName(pages, docName) &&
data !== undefined;
const [creatingKey, setCreatingKey] = useState<string | null>(null);
const [expanded, setExpanded] = useState(false);
const [prevDocName, setPrevDocName] = useState(docName);
if (prevDocName !== docName) {
setPrevDocName(docName);
setExpanded(false);
setCreatingKey(null);
}
const visible = expanded ? links : links.slice(0, INITIAL_VISIBLE);
async function handleCreatePage(seed: CreatePageSeed, key: string) {
if (creatingKey) return;
setCreatingKey(key);
try {
await createPageFromSeedAndUpdate(seed, {
addPage,
onCreated: (createdDocName) => {
onDestinationRequested?.(createdDocName);
navigateToDocHash(createdDocName);
},
});
setCreatingKey(null);
} catch (err) {
toast.error(err instanceof Error ? err.message : t`Failed to create page`);
setCreatingKey(null);
}
}
function renderRow(link: ForwardLinkEntry) {
const { title: linkTitle } = link;
if (link.kind === 'external') {
const titleIsUrl = link.title === link.url;
return (
<LinkRow
key={`ext:${link.url}`}
icon={<ArrowUpRight className="size-3.5" />}
rowTooltip={t`Opens in a new tab`}
title={link.title}
path={titleIsUrl ? undefined : link.url}
titleHover={link.url}
snippet={link.snippet}
href={link.url}
external
/>
);
}
const linkIntent = resolveLinkTargetIntent(link.docName, {
pages,
folderPaths,
pagesBySlug,
pagesByBasename,
});
const unresolved = !pagesLoading && linkIntent.kind === 'create';
const folderTarget =
!pagesLoading && linkIntent.kind === 'navigate' && linkIntent.displayState === 'folder';
const path = compactDocPath(link.docName);
const titleEqualsDocName = link.title === link.docName;
const displayTitle = titleEqualsDocName ? path : link.title;
const key = `doc:${link.docName}:${link.anchor ?? ''}`;
const navigateHashDocName =
linkIntent.kind === 'navigate' ? linkIntent.hashDocName : link.docName;
const navigateHref =
linkIntent.kind === 'navigate' && linkIntent.hash
? linkIntent.hash
: hashFromDocName(navigateHashDocName, link.anchor);
if (unresolved && linkIntent.kind === 'create') {
const seed = {
initialDir: linkIntent.initialDir,
suggestedName: linkIntent.suggestedName,
};
return (
<LinkRow
key={key}
icon={<TriangleAlert className="size-3.5" />}
iconColorClass="text-warning"
rowTooltip={creatingKey === key ? t`Creating page` : t`Missing page — click to create`}
ariaLabel={
creatingKey === key
? t`Creating page: ${linkTitle}.`
: t`Missing page: ${linkTitle}. Click to create.`
}
title={displayTitle}
path={path}
titleHover={link.docName}
anchor={link.anchor}
snippet={link.snippet}
disabled={creatingKey !== null}
onClick={() => void handleCreatePage(seed, key)}
/>
);
}
if (folderTarget && linkIntent.kind === 'navigate') {
return (
<LinkRow
key={key}
icon={<Folder className="size-3.5" />}
iconColorClass="text-info"
ariaLabel={t`Folder target: ${linkTitle}. Click to open the overview.`}
title={displayTitle}
path={path}
titleHover={link.docName}
anchor={link.anchor}
snippet={link.snippet}
href={navigateHref}
onClick={() => onDestinationRequested?.(navigateHashDocName)}
/>
);
}
return (
<LinkRow
key={key}
icon={<File className="size-3.5" />}
title={displayTitle}
path={path}
titleHover={link.docName}
anchor={link.anchor}
snippet={link.snippet}
href={navigateHref}
onClick={() => onDestinationRequested?.(navigateHashDocName)}
/>
);
}
return (
<Collapsible defaultOpen>
<SectionTrigger
title={t`Outgoing`}
count={error !== null || isUnresolvable ? null : links.length}
isLoading={isLoading}
/>
<CollapsibleContent>
<div className="px-2 pb-3" aria-busy={isLoading}>
{isUnresolvable ? (
<div className="px-3">
<PanelEmpty role="status">
<Trans>This page is no longer at this path.</Trans>
</PanelEmpty>
</div>
) : error ? (
<div className="px-3">
<PanelError>
{error instanceof Error ? error.message : t`Failed to load outgoing links`}
</PanelError>
</div>
) : links.length === 0 && !isLoading ? (
<div className="px-3">
<PanelEmpty>
<Trans>This page doesn't link to anything yet.</Trans>
</PanelEmpty>
</div>
) : (
<>
<div className="flex flex-col gap-1">{visible.map(renderRow)}</div>
<ShowMoreButton
total={links.length}
expanded={expanded}
onToggle={() => setExpanded((prev) => !prev)}
/>
</>
)}
</div>
</CollapsibleContent>
</Collapsible>
);
}
function LocalFilesSection({
docName,
onDestinationComplete,
}: {
docName: string;
onDestinationComplete?: (target?: HTMLElement) => void;
}) {
const { t } = useLingui();
const { pages, loading: pagesLoading, error: pageListError } = usePageList();
const { data, isLoading, error } = useQuery({
queryKey: ['forward-links', docName],
queryFn: () => fetchForwardLinks(docName),
enabled: !pagesLoading && isKnownPageDocName(pages, docName),
});
const isUnresolvable =
!pagesLoading &&
pageListError === null &&
!isKnownPageDocName(pages, docName) &&
data !== undefined;
const [expanded, setExpanded] = useState(false);
const [prevDocName, setPrevDocName] = useState(docName);
if (prevDocName !== docName) {
setPrevDocName(docName);
setExpanded(false);
}
const localTargets = data?.localTargets;
const rows = localTargets ?? [];
const visible = expanded ? rows : rows.slice(0, INITIAL_VISIBLE);
function navigateToOccurrence(target: ForwardLinkLocalTarget): void {
const detail: LintNavDetail = {
docName,
line: target.line + 1,
column: target.column + 1,
source: 'links',
onNavigated: onDestinationComplete,
};
rememberPendingSourceNavigation(docName, { kind: 'lint', detail });
window.dispatchEvent(new CustomEvent(LINT_NAV_EVENT, { detail }));
}
function renderLocalTargetRow(target: ForwardLinkLocalTarget) {
const isImage = target.role === 'image';
const resolved = target.status === 'exact' || target.status === 'fallback';
const identity = target.resolvedTarget ?? target.href;
const excluded = target.reason === 'excluded';
const statusWord = excluded
? t`Excluded`
: target.status === 'missing'
? t`Missing`
: t`Unresolvable`;
const ariaLabel = resolved
? isImage
? t`Image ${identity}. Go to reference.`
: t`File ${identity}. Go to reference.`
: excluded
? isImage
? t`Excluded image ${identity}. Go to reference.`
: t`Excluded file ${identity}. Go to reference.`
: target.status === 'missing'
? isImage
? t`Missing image ${identity}. Go to reference.`
: t`Missing file ${identity}. Go to reference.`
: isImage
? t`Unresolvable image ${identity}. Go to reference.`
: t`Unresolvable file ${identity}. Go to reference.`;
return (
<LinkRow
key={`lt:${target.range.start}-${target.range.end}`}
icon={isImage ? <ImageIcon className="size-3.5" /> : <File className="size-3.5" />}
iconColorClass={resolved ? undefined : 'text-warning'}
title={compactDocPath(identity)}
titleHover={identity}
ariaLabel={ariaLabel}
trailing={
resolved ? undefined : (
<Badge variant="outline" className="font-normal text-muted-foreground">
{statusWord}
</Badge>
)
}
onClick={() => navigateToOccurrence(target)}
/>
);
}
return (
<Collapsible defaultOpen>
<SectionTrigger
title={t`Local files`}
count={error !== null || isUnresolvable ? null : rows.length}
isLoading={isLoading}
/>
<CollapsibleContent>
<div className="px-2 pb-3" aria-busy={isLoading}>
{isUnresolvable ? (
<div className="px-3">
<PanelEmpty role="status">
<Trans>This page is no longer at this path.</Trans>
</PanelEmpty>
</div>
) : error ? (
<div className="px-3">
<PanelError>
{error instanceof Error ? error.message : t`Failed to load local files`}
</PanelError>
</div>
) : localTargets === undefined && !isLoading ? (
<div className="px-3">
<PanelEmpty>
<Trans>Local file details aren't available yet.</Trans>
</PanelEmpty>
</div>
) : rows.length === 0 && !isLoading ? (
<div className="px-3">
<PanelEmpty>
<Trans>This page references no local files or images.</Trans>
</PanelEmpty>
</div>
) : (
<>
<div className="flex flex-col gap-1">{visible.map(renderLocalTargetRow)}</div>
<ShowMoreButton
total={rows.length}
expanded={expanded}
onToggle={() => setExpanded((prev) => !prev)}
/>
</>
)}
</div>
</CollapsibleContent>
</Collapsible>
);
}
export function LinksPanel({
docName,
className = '',
onDestinationRequested,
onDestinationComplete,
}: {
docName: string;
className?: string;
onDestinationRequested?: (docName: string) => void;
onDestinationComplete?: (target?: HTMLElement) => void;
}) {
return (
<Panel className={className}>
<PanelBody className="px-0 py-0">
<ForwardLinksSection docName={docName} onDestinationRequested={onDestinationRequested} />
<Separator />
<LocalFilesSection docName={docName} onDestinationComplete={onDestinationComplete} />
<Separator />
<BacklinksSection docName={docName} onDestinationRequested={onDestinationRequested} />
</PanelBody>
</Panel>
);
}