apps/web/app/routes/workspace/docs/page.tsx · flagon-io/g1t

Docs: a workspace knowledge base people and agents write together1d ago

1

import { DOC_AGENT_MODE_LABELS, DOC_ROLE_LABELS, type DocPage, type DocPageDetail, type DocSuggestion, type DocsLiveEvent, type MemberProfile } from "@g1t/contracts";

2

import {

3

ArrowRightLeft,

4

Check,

5

ClipboardCopy,

6

Copy,

7

Download,

8

Ellipsis,

9

History,

10

ImagePlus,

11

LayoutTemplate,

12

Link2,

13

MessageSquare,

14

Share2,

15

SmilePlus,

16

Sparkles,

17

Star,

18

Trash2,

19

WifiOff,

20

} from "lucide-react";

21

import { type ComponentType, Suspense, lazy, useCallback, useEffect, useMemo, useRef, useState } from "react";

22

import { Link, data, redirect, useNavigate, useRevalidator, useRouteLoaderData } from "react-router";

23

24

import type { Route } from "./+types/page";

25

import { docsRequest, useDocsAction, useDocsData } from "../../../components/docs/actions";

26

import type { DocEditorProps, Presence } from "../../../components/docs/editor";

27

import { EditorSkeleton } from "../../../components/docs/editor-skeleton";

28

import { CoverPicker, Discussion, HistoryDialog, IconPicker, MoveDialog, SuggestionCard, TemplateDialog, type PageThread } from "../../../components/docs/page-parts";

29

import { Crumbs, Face, Faces } from "../../../components/docs/parts";

30

import type { LiveStatus } from "../../../components/docs/provider";

31

import { PageIcon } from "../../../components/docs/sidebar";

32

import { type Who, whoAre } from "../../../components/docs/who";

33

import { Markdown } from "../../../components/markdown";

34

import { ErrorText, TimeAgo } from "../../../components/ui";

35

import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger } from "../../../components/ui/dropdown-menu";

36

import { Hint } from "../../../components/ui/hint";

37

import { Popover, PopoverContent, PopoverTrigger } from "../../../components/ui/popover";

38

import { usercontentFrom } from "../../../lib/addresses";

39

import { canDo, coverStyle, pageIdOf, pagePath, readingTime } from "../../../lib/docs";

40

import { page as pageMeta } from "../../../lib/meta";

41

import { docs } from "../../../lib/services.server";

42

import { requireUser, roleIn } from "../../../lib/session.server";

43

44

/**

45

* The editor and everything it brings, loaded only in the browser, after

46

* the page shows. The server's bundle never includes it: the server

47

* renders the page's Markdown instead.

48

*/

49

const DocEditor = lazy(

50

(): Promise<{ default: ComponentType<DocEditorProps> }> => (import.meta.env.SSR ? Promise.resolve({ default: () => null }) : import("../../../components/docs/editor")),

51

);

52

53

export function meta({ loaderData: loaded, params, ...args }: Route.MetaArgs) {

54

const p = loaded?.detail.page;

55

return pageMeta(args, { title: `${p ? `${p.icon ? `${p.icon} ` : ""}${p.title || "Untitled"}` : "Page"} · ${params.owner} · g1t`, description: p?.excerpt, type: "article" });

56

}

57

58

export async function loader({ params, context, request }: Route.LoaderArgs): Promise<{ detail: DocPageDetail }> {

59

const viewer = requireUser(context, request);

60

if (!roleIn(viewer, params.owner)) throw data(null, { status: 404 });

61

const id = pageIdOf(params.page);

62

if (!id) throw data(null, { status: 404 });

63

const found = await docs.page(params.owner.toLowerCase(), id, viewer);

64

if (!found.ok) throw data(null, { status: found.error.code === "not_found" ? 404 : 403 });

65

const detail = found.value;

66

// An old address (renamed page, moved space) goes to the current one.

67

const url = new URL(request.url);

68

if (url.pathname !== detail.page.path) throw redirect(`${detail.page.path}${url.search}`);

69

return { detail };

70

}

71

72

function useHydrated() {

73

const [hydrated, setHydrated] = useState(false);

74

useEffect(() => setHydrated(true), []);

75

return hydrated;

76

}

77

78

/** One page: its header, the live editor (or its Markdown until the editor loads), suggestions, comments, links. */

79

export default function DocPageView({ loaderData, params }: Route.ComponentProps) {

80

const slug = params.owner.toLowerCase();

81

const { detail } = loaderData;

82

const { page, space } = detail;

83

const layout = useDocsData();

84

const root = useRouteLoaderData("root");

85

const usercontent = usercontentFrom(root);

86

const navigate = useNavigate();

87

const revalidator = useRevalidator();

88

const hydrated = useHydrated();

89

const { send, error, setError } = useDocsAction(slug);

90

91

const [role, setRole] = useState(detail.role);

92

useEffect(() => setRole(detail.role), [detail.role, page.id]);

93

const editable = canDo(role, "edit");

94

95

// The header follows the page, and anyone renaming it live.

96

const [live, setLive] = useState<DocPage>(page);

97

useEffect(() => setLive(page), [page]);

98

const [title, setTitle] = useState(page.title);

99

const titleFocused = useRef(false);

100

useEffect(() => {

101

if (!titleFocused.current) setTitle(live.title);

102

}, [live.title]);

103

const saveTimer = useRef<ReturnType<typeof setTimeout> | null>(null);

104

const saveTitle = (next: string) => {

105

setTitle(next);

106

if (saveTimer.current) clearTimeout(saveTimer.current);

107

saveTimer.current = setTimeout(() => void send("update_page", { page_id: page.id, change: { title: next } }), 700);

108

};

109

110

const [suggestions, setSuggestions] = useState<DocSuggestion[]>(detail.suggestions);

111

useEffect(() => setSuggestions(detail.suggestions), [detail.suggestions]);

112

const [presence, setPresence] = useState<Presence[]>([]);

113

const [status, setStatus] = useState<LiveStatus>("connecting");

114

const [archived, setArchived] = useState(!!page.archived_at);

115

useEffect(() => setArchived(!!page.archived_at), [page.archived_at]);

116

const [showComments, setShowComments] = useState(false);

117

const [history, setHistory] = useState(false);

118

const [moving, setMoving] = useState(false);

119

const [templating, setTemplating] = useState(false);

120

const [favorite, setFavorite] = useState(detail.favorite);

121

useEffect(() => setFavorite(detail.favorite), [detail.favorite]);

122

const [copied, setCopied] = useState<string | null>(null);

123

const [threads, setThreads] = useState<PageThread[]>([]);

124

const [names, setNames] = useState<Map<string, Who>>(new Map());

125

useEffect(() => {

126

const keys = threads.flatMap((t) => t.comments.map((c) => c.author));

127

if (keys.some((k) => !names.has(k))) void whoAre(slug, keys).then((found) => setNames((was) => new Map([...was, ...found])));

128

}, [threads, slug, names]);

129

130

const onEvent = useCallback(

131

(event: DocsLiveEvent) => {

132

if (event.type === "page.updated") setLive(event.page);

133

else if (event.type === "page.archived") setArchived(true);

134

else if (event.type === "access") {

135

if (event.role) setRole(event.role);

136

else navigate(`/${slug}/-/docs`);

137

} else if (event.type === "suggestion.created") setSuggestions((was) => [...was.filter((s) => s.id !== event.suggestion.id), event.suggestion]);

138

else if (event.type === "suggestion.updated") setSuggestions((was) => (event.suggestion.status === "open" ? was.map((s) => (s.id === event.suggestion.id ? event.suggestion : s)) : was.filter((s) => s.id !== event.suggestion.id)));

139

else if (event.type === "version.created") void revalidator.revalidate();

140

},

141

[navigate, slug, revalidator],

142

);

143

144

const decide = async (id: string, decision: "accept" | "reject") => {

145

setSuggestions((was) => was.filter((s) => s.id !== id));

146

const done = await send("decide", { suggestion_id: id, decision }, { reload: false });

147

if (!done.ok) void revalidator.revalidate();

148

};

149

150

const people = useCallback(

151

(key: string): Pick<MemberProfile, "kind" | "id" | "name" | "display_name" | "avatar" | "avatar_seed"> => {

152

const at = key.indexOf(":");

153

const kind = key.slice(0, at) === "agent" ? "agent" : "user";

154

const id = key.slice(at + 1);

155

if (layout?.me.key === key) return { kind: "user", id, name: layout.me.name, display_name: layout.me.display_name, avatar: layout.me.avatar, avatar_seed: null };

156

const found = names.get(key);

157

return { kind, id, name: found?.name ?? "someone", display_name: found?.display_name ?? (kind === "agent" ? "An agent" : "Someone"), avatar: found?.avatar ?? null, avatar_seed: found?.avatar_seed ?? null };

158

},

159

[layout, names],

160

);

161

162

const threadRequest = async (path: string, method: string, body: unknown) => {

163

try {

164

const r = await fetch(`/${slug}/-/docs/threads/${page.id}${path}`, { method, headers: { "content-type": "application/json" }, body: JSON.stringify(body) });

165

if (!r.ok) {

166

const result = (await r.json().catch(() => null)) as { error?: { message?: string } } | null;

167

setError(result?.error?.message ?? "That comment didn't go through.");

168

return false;

169

}

170

return true;

171

} catch {

172

setError("That comment didn't go through.");

173

return false;

174

}

175

};

176

/** A comment's text as the editor's comments hold it: blocks, with @mentions as mentions. */

177

const commentBody = (text: string) => {

178

const parts: unknown[] = [];

179

for (const piece of text.split(/(@[a-z0-9][a-z0-9-]*)/i)) {

180

const who = piece.startsWith("@") ? layout?.mentionables.find((m) => m.name.toLowerCase() === piece.slice(1).toLowerCase()) : null;

181

if (who) parts.push({ type: "mention", props: { kind: who.kind, id: who.id, name: who.name, href: "" } });

182

else if (piece) parts.push({ type: "text", text: piece, styles: {} });

183

}

184

return [{ type: "paragraph", content: parts, children: [] }];

185

};

186

187

const copy = async (what: "link" | "markdown") => {

188

try {

189

if (what === "link") await navigator.clipboard.writeText(`${window.location.origin}${pagePath(slug, space.slug, live.title, page.id)}`);

190

else {

191

const r = await fetch(`/${slug}/-/docs/export?page=${encodeURIComponent(page.id)}`);

192

await navigator.clipboard.writeText(await r.text());

193

}

194

setCopied(what);

195

setTimeout(() => setCopied(null), 1600);

196

} catch {

197

setError("Your browser didn't allow copying.");

198

}

199

};

200

201

const cover = coverStyle(live.cover);

202

const reading = useMemo(() => readingTime(detail.markdown), [detail.markdown]);

203

const others = presence.filter((p) => !p.me);

204

const crumbs = [

205

{ label: "Docs", to: `/${slug}/-/docs` },

206

{ label: space.name, to: `/${slug}/-/docs/${space.slug}` },

207

...detail.breadcrumbs.map((b) => ({ label: `${b.icon ? `${b.icon} ` : ""}${b.title || "Untitled"}`, to: b.path })),

208

];

209

210

return (

211

212

{cover && (

213

214

{editable && (

215

<CoverPicker onChange={(c) => send("update_page", { page_id: page.id, change: { cover: c } })}>

216

217

Change cover

218

</button>

219

</CoverPicker>

220

)}

221

</div>

222

)}

223

{/* The bar above the page: where it is, who is here, and what can be done. */}

224

225

226

227

</div>

228

{status === "offline" && (

229

230

231

<WifiOff size={13} /> Offline

232

</span>

233

</Hint>

234

)}

235

{others.length > 0 && (

236

237

{others.slice(0, 5).map((p) => (

238

239

240

241

</span>

242

</Hint>

243

))}

244

{others.length > 5 && <span className="pl-3 text-xs text-faint">+{others.length - 5}</span>}

245

</span>

246

)}

247

248

<button type="button" onClick={() => setShowComments(!showComments)} aria-pressed={showComments} aria-label="Comments" className={`hidden size-8 items-center justify-center rounded-md xl:flex ${showComments ? "bg-raised text-fg" : "text-faint hover:bg-raised hover:text-fg"}`}>

249

250

</button>

251

</Hint>

252

253

<button

254

type="button"

255

aria-label={favorite ? "Remove from favorites" : "Add to favorites"}

256

aria-pressed={favorite}

257

onClick={async () => {

258

setFavorite(!favorite);

259

await send("favorite", { page_id: page.id, on: !favorite });

260

}}

261

className="flex size-8 items-center justify-center rounded-md text-faint hover:bg-raised hover:text-fg"

262

>

263

264

</button>

265

</Hint>

266

267

268

269

<Share2 size={13} /> Share

270

</button>

271

</PopoverTrigger>

272

273

274

275

Everyone with access to <span className="text-fg">{space.name}</span>:{" "}

276

{space.kind === "workspace" ? `the whole workspace (${space.default_role ? DOC_ROLE_LABELS[space.default_role].toLowerCase() : "listed members only"})` : space.kind === "team" ? `the ${space.team} team, and members added to the space` : "only the space's members"}. Agents here: {DOC_AGENT_MODE_LABELS[space.agent_mode].toLowerCase()}.

277

</p>

278

<p className="mt-2 text-xs text-muted">Your access: {DOC_ROLE_LABELS[role].toLowerCase()}.</p>

279

280

<button type="button" onClick={() => copy("link")} className="inline-flex h-8 items-center gap-1.5 rounded-md bg-raised px-2.5 text-xs hover:bg-line">

281

{copied === "link" ? <Check size={13} /> : <Link2 size={13} />} {copied === "link" ? "Copied" : "Copy link"}

282

</button>

283

{canDo(space.viewer_role, "manage") && (

284

285

Space access

286

</Link>

287

)}

288

</div>

289

</PopoverContent>

290

</Popover>

291

292

293

294

295

</button>

296

</DropdownMenuTrigger>

297

298

<DropdownMenuItem onSelect={() => setHistory(true)}>

299

<History size={14} /> History

300

</DropdownMenuItem>

301

<DropdownMenuItem onSelect={() => copy("markdown")}>

302

<ClipboardCopy size={14} /> Copy as Markdown

303

</DropdownMenuItem>

304

305

306

<Download size={14} /> Export Markdown

307

</a>

308

</DropdownMenuItem>

309

310

<Link2 size={14} /> Copy link

311

</DropdownMenuItem>

312

{editable && (

313

<>

314

315

<DropdownMenuItem onSelect={() => setMoving(true)}>

316

<ArrowRightLeft size={14} /> Move

317

</DropdownMenuItem>

318

<DropdownMenuItem

319

onSelect={async () => {

320

const made = await docsRequest<DocPage>(slug, "duplicate_page", { page_id: page.id });

321

if (made.ok) navigate(made.value.path);

322

else setError(made.error.message);

323

}}

324

>

325

<Copy size={14} /> Duplicate

326

</DropdownMenuItem>

327

</>

328

)}

329

<DropdownMenuItem onSelect={() => setTemplating(true)}>

330

<LayoutTemplate size={14} /> Save as template

331

</DropdownMenuItem>

332

{editable && (

333

<>

334

335

<DropdownMenuItem

336

onSelect={async () => {

337

const done = await send("archive_page", { page_id: page.id });

338

if (done.ok) navigate(`/${slug}/-/docs/${space.slug}`);

339

}}

340

className="text-danger focus:text-danger"

341

>

342

<Trash2 size={14} /> Move to trash

343

</DropdownMenuItem>

344

</>

345

)}

346

</DropdownMenuContent>

347

</DropdownMenu>

348

</div>

349

350

351

352

{archived && (

353

354

This page was moved to the trash.{" "}

355

356

Open the trash

357

</Link>

358

</p>

359

)}

360

{/* Icon, cover, title. */}

361

362

{live.icon && (

363

<IconPicker value={live.icon} onChange={(icon) => editable && send("update_page", { page_id: page.id, change: { icon } })}>

364

365

{live.icon}

366

</button>

367

</IconPicker>

368

)}

369

{editable && (

370

371

{!live.icon && (

372

<IconPicker value={null} onChange={(icon) => send("update_page", { page_id: page.id, change: { icon } })}>

373

374

<SmilePlus size={13} /> Add icon

375

</button>

376

</IconPicker>

377

)}

378

{!cover && (

379

<CoverPicker onChange={(c) => send("update_page", { page_id: page.id, change: { cover: c } })}>

380

381

<ImagePlus size={13} /> Add cover

382

</button>

383

</CoverPicker>

384

)}

385

</div>

386

)}

387

{editable ? (

388

<textarea

389

value={title}

390

rows={1}

391

placeholder="Untitled"

392

aria-label="Title"

393

onFocus={() => (titleFocused.current = true)}

394

onBlur={() => (titleFocused.current = false)}

395

onChange={(e) => saveTitle(e.target.value.replace(/\n/g, " "))}

396

onKeyDown={(e) => {

397

if (e.key === "Enter") {

398

e.preventDefault();

399

(document.querySelector(".g1t-editor .bn-editor") as HTMLElement | null)?.focus();

400

}

401

}}

402

className="field-sizing-content w-full resize-none bg-transparent font-display text-4xl leading-tight font-semibold tracking-tight text-fg outline-none placeholder:text-faint/60"

403

/>

404

) : (

405

<h1 className="font-display text-4xl leading-tight font-semibold tracking-tight">{live.title || "Untitled"}</h1>

406

)}

407

</div>

408

{/* Who wrote it, who owns it, what it's about. */}

409

410

{live.updated_by && (

411

412

413

Last edited by <span className="text-muted">{live.updated_by.display_name}</span> · <TimeAgo at={live.updated_at} />

414

</span>

415

)}

416

{live.owners.length > 0 && (

417

418

Owners <Faces people={live.owners} size={18} />

419

</span>

420

)}

421

{[...new Set([...live.projects, ...space.projects])].map((p) => (

422

423

{p}

424

</Link>

425

))}

426

<span>

427

{reading.words.toLocaleString()} words · {reading.minutes} min read

428

</span>

429

{!editable && <span className="rounded-full bg-raised px-2 py-0.5">{DOC_ROLE_LABELS[role]}</span>}

430

</div>

431

{error && (

432

433

<ErrorText>{error}</ErrorText>

434

</div>

435

)}

436

437

{/* Agents' suggestions, all together on a narrower screen (beside their blocks on a wide one). */}

438

{suggestions.length > 0 && (

439

440

441

442

443

{suggestions.length} {suggestions.length === 1 ? "suggestion" : "suggestions"} waiting

444

</span>

445

{editable && suggestions.length > 1 && (

446

<button type="button" onClick={async () => { setSuggestions([]); await send("accept_all", { page_id: page.id }); }} className="text-xs font-medium text-accent hover:underline">

447

Accept all

448

</button>

449

)}

450

</div>

451

452

{suggestions.map((s) => (

453

454

))}

455

</div>

456

</div>

457

)}

458

{suggestions.length > 1 && editable && (

459

460

<button type="button" onClick={async () => { setSuggestions([]); await send("accept_all", { page_id: page.id }); }} className="inline-flex h-8 items-center gap-1.5 rounded-md bg-accent/15 px-3 text-xs font-medium text-accent hover:bg-accent/25">

461

<Check size={13} /> Accept all {suggestions.length} suggestions

462

</button>

463

</div>

464

)}

465

</div>

466

467

{/* The page itself: live once the editor loads; its saved Markdown until then. */}

468

469

{hydrated && !archived ? (

470

471

<DocEditor

472

key={page.id}

473

slug={slug}

474

pageId={page.id}

475

role={role}

476

me={layout?.me ?? { key: "", name: "", display_name: "", avatar: null }}

477

mentionables={layout?.mentionables ?? []}

478

usercontent={usercontent}

479

suggestions={suggestions}

480

showComments={showComments}

481

onPresence={setPresence}

482

onStatus={setStatus}

483

onEvent={onEvent}

484

onPageThreads={setThreads}

485

renderSuggestion={(s) => <SuggestionCard suggestion={s} canDecide={editable} onDecide={decide} />}

486

/>

487

</Suspense>

488

) : (

489

490

)}

491

</div>

492

493

494

{(detail.children.length > 0 || detail.backlinks.length > 0) && (

495

496

{detail.children.length > 0 && (

497

498

<h2 className="mb-2 text-xs font-medium tracking-wide text-faint uppercase">Pages inside</h2>

499

500

{detail.children.map((c) => (

501

502

503

<PageIcon icon={c.icon} /> {c.title || "Untitled"}

504

</Link>

505

</li>

506

))}

507

</ul>

508

</section>

509

)}

510

{detail.backlinks.length > 0 && (

511

512

<h2 className="mb-2 text-xs font-medium tracking-wide text-faint uppercase">Linked from</h2>

513

514

{detail.backlinks.map((c) => (

515

516

517

<PageIcon icon={c.icon} /> {c.title || "Untitled"}

518

</Link>

519

</li>

520

))}

521

</ul>

522

</section>

523

)}

524

</div>

525

)}

526

{hydrated && (

527

<Discussion

528

threads={threads}

529

people={people}

530

canComment={canDo(role, "comment")}

531

onPost={(text) => threadRequest("", "POST", { initialComment: { body: commentBody(text) }, page_level: true })}

532

onReply={(thread, text) => threadRequest(`/${encodeURIComponent(thread)}/comments`, "POST", { comment: { body: commentBody(text) } })}

533

onResolve={(thread, resolved) => void threadRequest(`/${encodeURIComponent(thread)}/${resolved ? "resolve" : "unresolve"}`, "POST", {})}

534

/>

535

)}

536

</div>

537

</article>

538

539

<HistoryDialog slug={slug} pageId={page.id} open={history} onOpenChange={setHistory} canRestore={editable} onRestore={(versionId) => send("restore_version", { page_id: page.id, version_id: versionId })} />

540

{layout?.sidebar && (

541

<MoveDialog

542

spaces={layout.sidebar.spaces}

543

pageId={page.id}

544

current={{ space_id: page.space_id, parent_id: page.parent_id }}

545

open={moving}

546

onOpenChange={setMoving}

547

onMove={async (spaceId, parentId) => {

548

const moved = await send<DocPage>("move_page", { page_id: page.id, move: { space_id: spaceId, parent_id: parentId, before_id: null } });

549

setMoving(false);

550

if (moved.ok) navigate(moved.value.path);

551

}}

552

/>

553

)}

554

<TemplateDialog open={templating} onOpenChange={setTemplating} title={live.title || "Untitled"} onSave={(name, description) => send("save_template", { page_id: page.id, name, description })} />

555

</div>

556

);

557

}

558

559

/** The page as Markdown: what shows before the editor loads, and what a reader without script sees. */

560

function ReadView({ markdown }: { markdown: string }) {

561

if (!markdown.trim()) return <EditorSkeleton />;

562

return (

563

564

565

</div>

566

);

567

}