From 005ad56188534a5bd2dfc1334bcf6daac4aeca65 Mon Sep 17 00:00:00 2001
From: JohnDoe6345789 <john.doe6345789@gmail.com>
Date: Fri, 26 Dec 2025 02:24:10 +0000
Subject: [PATCH] docs: nextjs,frontends,get (16 files)

---
 README.md                                     |   2 +
 .../src/components/level/ModeratorPanel.tsx   | 201 ++++++++++++++++++
 .../{ => field}/get-default-value.ts          |   0
 .../functions/{ => field}/get-field-label.ts  |   0
 .../functions/{ => field}/get-help-text.ts    |   0
 .../functions/{ => field}/validate-field.ts   |   0
 .../functions/{ => model}/find-model.ts       |   0
 .../functions/{ => model}/get-model-key.ts    |   0
 .../{ => model}/get-model-label-plural.ts     |   0
 .../functions/{ => model}/get-model-label.ts  |   0
 .../{ => record/crud}/create-empty-record.ts  |   0
 .../{ => record/crud}/generate-id.ts          |   0
 .../functions/{ => record}/filter-records.ts  |   0
 .../functions/{ => record}/get-records-key.ts |   0
 .../functions/{ => record}/sort-records.ts    |   0
 .../functions/{ => record}/validate-record.ts |   0
 16 files changed, 203 insertions(+)
 create mode 100644 frontends/nextjs/src/components/level/ModeratorPanel.tsx
 rename frontends/nextjs/src/lib/schema/functions/{ => field}/get-default-value.ts (100%)
 rename frontends/nextjs/src/lib/schema/functions/{ => field}/get-field-label.ts (100%)
 rename frontends/nextjs/src/lib/schema/functions/{ => field}/get-help-text.ts (100%)
 rename frontends/nextjs/src/lib/schema/functions/{ => field}/validate-field.ts (100%)
 rename frontends/nextjs/src/lib/schema/functions/{ => model}/find-model.ts (100%)
 rename frontends/nextjs/src/lib/schema/functions/{ => model}/get-model-key.ts (100%)
 rename frontends/nextjs/src/lib/schema/functions/{ => model}/get-model-label-plural.ts (100%)
 rename frontends/nextjs/src/lib/schema/functions/{ => model}/get-model-label.ts (100%)
 rename frontends/nextjs/src/lib/schema/functions/{ => record/crud}/create-empty-record.ts (100%)
 rename frontends/nextjs/src/lib/schema/functions/{ => record/crud}/generate-id.ts (100%)
 rename frontends/nextjs/src/lib/schema/functions/{ => record}/filter-records.ts (100%)
 rename frontends/nextjs/src/lib/schema/functions/{ => record}/get-records-key.ts (100%)
 rename frontends/nextjs/src/lib/schema/functions/{ => record}/sort-records.ts (100%)
 rename frontends/nextjs/src/lib/schema/functions/{ => record}/validate-record.ts (100%)

diff --git a/README.md b/README.md
index c8108a051..f523817ab 100644
--- a/README.md
+++ b/README.md
@@ -618,6 +618,8 @@ npm run act:build     # Test build only
 npm run act:diagnose  # Check setup (no Docker)
 ```
 
+Refer to [`docs/guides/ACT_CHEAT_SHEET.md`](./docs/guides/ACT_CHEAT_SHEET.md) or the detailed [`docs/guides/ACT_TESTING.md`](./docs/guides/ACT_TESTING.md) guide to mirror GitHub Actions workflows locally and understand each Act mode.
+
 ---
 
 ## Development
diff --git a/frontends/nextjs/src/components/level/ModeratorPanel.tsx b/frontends/nextjs/src/components/level/ModeratorPanel.tsx
new file mode 100644
index 000000000..f3eb9acfc
--- /dev/null
+++ b/frontends/nextjs/src/components/level/ModeratorPanel.tsx
@@ -0,0 +1,201 @@
+"use client"
+
+import { useEffect, useMemo, useState } from 'react'
+import { Button } from '@/components/ui'
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui'
+import { Badge } from '@/components/ui'
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@/components/ui'
+import { Stack, Typography } from '@/components/ui'
+import { toast } from 'sonner'
+import { Database } from '@/lib/database'
+import type { Comment, User } from '@/lib/level-types'
+import { AppHeader } from '@/components/shared/AppHeader'
+
+const FLAGGED_TERMS = ['spam', 'error', 'abuse', 'illegal', 'urgent', 'offensive']
+
+interface ModeratorPanelProps {
+  user: User
+  onLogout: () => void
+  onNavigate: (level: number) => void
+}
+
+export function ModeratorPanel({ user, onLogout, onNavigate }: ModeratorPanelProps) {
+  const [comments, setComments] = useState<Comment[]>([])
+  const [resolvedIds, setResolvedIds] = useState<string[]>([])
+  const [isLoading, setIsLoading] = useState(true)
+
+  useEffect(() => {
+    let active = true
+    setIsLoading(true)
+
+    Database.getComments()
+      .then((latest) => {
+        if (active) {
+          setComments(latest)
+        }
+      })
+      .finally(() => {
+        if (active) {
+          setIsLoading(false)
+        }
+      })
+
+    return () => {
+      active = false
+    }
+  }, [])
+
+  const flaggedComments = useMemo(() => {
+    return comments.filter((comment) => {
+      if (resolvedIds.includes(comment.id)) {
+        return false
+      }
+      const content = comment.content.toLowerCase()
+      return FLAGGED_TERMS.some((term) => content.includes(term))
+    })
+  }, [comments, resolvedIds])
+
+  const handleResolve = (commentId: string) => {
+    if (resolvedIds.includes(commentId)) {
+      return
+    }
+    setResolvedIds((current) => [...current, commentId])
+    toast.success('Flag resolved and archived from the queue')
+  }
+
+  const highlightLabel = (term: string) => term.charAt(0).toUpperCase() + term.slice(1)
+
+  return (
+    <div className="min-h-screen bg-background">
+      <AppHeader
+        title="Moderator Desk"
+        username={user.username}
+        showBadge
+        showAvatar
+        variant="admin"
+        onNavigateHome={() => onNavigate(1)}
+        onLogout={onLogout}
+      />
+
+      <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-8 space-y-6">
+        <div className="space-y-2">
+          <Typography variant="h4">Moderation queue</Typography>
+          <Typography color="text.secondary">
+            Keep the community healthy by resolving flags, reviewing reports, and guiding the tone.
+          </Typography>
+        </div>
+
+        <div className="grid gap-6 md:grid-cols-3">
+          <Card>
+            <CardHeader>
+              <CardTitle>Flagged content</CardTitle>
+              <CardDescription>Automated signal based on keywords</CardDescription>
+            </CardHeader>
+            <CardContent>
+              <Typography variant="h3">{flaggedComments.length}</Typography>
+              <Typography color="text.secondary" className="mt-2">
+                Pending items in the moderation queue
+              </Typography>
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle>Resolved this session</CardTitle>
+            </CardHeader>
+            <CardContent>
+              <Typography variant="h3">{resolvedIds.length}</Typography>
+              <Typography color="text.secondary" className="mt-2">
+                Items you flagged as handled
+              </Typography>
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle>Community signals</CardTitle>
+            </CardHeader>
+            <CardContent>
+              <Stack direction="row" spacing={1} flexWrap="wrap">
+                {FLAGGED_TERMS.map((term) => (
+                  <Badge key={term}>{highlightLabel(term)}</Badge>
+                ))}
+              </Stack>
+              <Typography color="text.secondary" className="mt-2">
+                Track the keywords that pulled items into the queue
+              </Typography>
+            </CardContent>
+          </Card>
+        </div>
+
+        <Card>
+          <CardHeader>
+            <div className="flex items-center justify-between gap-4">
+              <div>
+                <CardTitle>Flagged comments</CardTitle>
+                <CardDescription>A curated view of the comments that triggered a signal</CardDescription>
+              </div>
+              <Button variant="ghost" size="sm" onClick={() => onNavigate(2)}>
+                Go to user dashboard
+              </Button>
+            </div>
+          </CardHeader>
+          <CardContent>
+            {isLoading ? (
+              <Typography color="text.secondary">Loading flagged comments…</Typography>
+            ) : flaggedComments.length === 0 ? (
+              <Typography color="text.secondary">
+                No flagged comments at the moment. Enjoy the calm.
+              </Typography>
+            ) : (
+              <Table>
+                <TableHeader>
+                  <TableRow>
+                    <TableHead>User</TableHead>
+                    <TableHead>Comment</TableHead>
+                    <TableHead>Matched terms</TableHead>
+                    <TableHead className="text-right">Actions</TableHead>
+                  </TableRow>
+                </TableHeader>
+                <TableBody>
+                  {flaggedComments.map((comment) => {
+                    const matches = FLAGGED_TERMS.filter((term) =>
+                      comment.content.toLowerCase().includes(term)
+                    )
+                    return (
+                      <TableRow key={comment.id}>
+                        <TableCell className="font-mono text-sm">{comment.userId}</TableCell>
+                        <TableCell>{comment.content}</TableCell>
+                        <TableCell>
+                          <Stack direction="row" spacing={1} flexWrap="wrap">
+                            {matches.map((match) => (
+                              <Badge key={`${comment.id}-${match}`} variant="outline">
+                                {match}
+                              </Badge>
+                            ))}
+                          </Stack>
+                        </TableCell>
+                        <TableCell className="text-right">
+                          <Button size="sm" variant="ghost" onClick={() => handleResolve(comment.id)}>
+                            Mark safe
+                          </Button>
+                        </TableCell>
+                      </TableRow>
+                    )
+                  })}
+                </TableBody>
+              </Table>
+            )}
+          </CardContent>
+        </Card>
+      </div>
+    </div>
+  )
+}
diff --git a/frontends/nextjs/src/lib/schema/functions/get-default-value.ts b/frontends/nextjs/src/lib/schema/functions/field/get-default-value.ts
similarity index 100%
rename from frontends/nextjs/src/lib/schema/functions/get-default-value.ts
rename to frontends/nextjs/src/lib/schema/functions/field/get-default-value.ts
diff --git a/frontends/nextjs/src/lib/schema/functions/get-field-label.ts b/frontends/nextjs/src/lib/schema/functions/field/get-field-label.ts
similarity index 100%
rename from frontends/nextjs/src/lib/schema/functions/get-field-label.ts
rename to frontends/nextjs/src/lib/schema/functions/field/get-field-label.ts
diff --git a/frontends/nextjs/src/lib/schema/functions/get-help-text.ts b/frontends/nextjs/src/lib/schema/functions/field/get-help-text.ts
similarity index 100%
rename from frontends/nextjs/src/lib/schema/functions/get-help-text.ts
rename to frontends/nextjs/src/lib/schema/functions/field/get-help-text.ts
diff --git a/frontends/nextjs/src/lib/schema/functions/validate-field.ts b/frontends/nextjs/src/lib/schema/functions/field/validate-field.ts
similarity index 100%
rename from frontends/nextjs/src/lib/schema/functions/validate-field.ts
rename to frontends/nextjs/src/lib/schema/functions/field/validate-field.ts
diff --git a/frontends/nextjs/src/lib/schema/functions/find-model.ts b/frontends/nextjs/src/lib/schema/functions/model/find-model.ts
similarity index 100%
rename from frontends/nextjs/src/lib/schema/functions/find-model.ts
rename to frontends/nextjs/src/lib/schema/functions/model/find-model.ts
diff --git a/frontends/nextjs/src/lib/schema/functions/get-model-key.ts b/frontends/nextjs/src/lib/schema/functions/model/get-model-key.ts
similarity index 100%
rename from frontends/nextjs/src/lib/schema/functions/get-model-key.ts
rename to frontends/nextjs/src/lib/schema/functions/model/get-model-key.ts
diff --git a/frontends/nextjs/src/lib/schema/functions/get-model-label-plural.ts b/frontends/nextjs/src/lib/schema/functions/model/get-model-label-plural.ts
similarity index 100%
rename from frontends/nextjs/src/lib/schema/functions/get-model-label-plural.ts
rename to frontends/nextjs/src/lib/schema/functions/model/get-model-label-plural.ts
diff --git a/frontends/nextjs/src/lib/schema/functions/get-model-label.ts b/frontends/nextjs/src/lib/schema/functions/model/get-model-label.ts
similarity index 100%
rename from frontends/nextjs/src/lib/schema/functions/get-model-label.ts
rename to frontends/nextjs/src/lib/schema/functions/model/get-model-label.ts
diff --git a/frontends/nextjs/src/lib/schema/functions/create-empty-record.ts b/frontends/nextjs/src/lib/schema/functions/record/crud/create-empty-record.ts
similarity index 100%
rename from frontends/nextjs/src/lib/schema/functions/create-empty-record.ts
rename to frontends/nextjs/src/lib/schema/functions/record/crud/create-empty-record.ts
diff --git a/frontends/nextjs/src/lib/schema/functions/generate-id.ts b/frontends/nextjs/src/lib/schema/functions/record/crud/generate-id.ts
similarity index 100%
rename from frontends/nextjs/src/lib/schema/functions/generate-id.ts
rename to frontends/nextjs/src/lib/schema/functions/record/crud/generate-id.ts
diff --git a/frontends/nextjs/src/lib/schema/functions/filter-records.ts b/frontends/nextjs/src/lib/schema/functions/record/filter-records.ts
similarity index 100%
rename from frontends/nextjs/src/lib/schema/functions/filter-records.ts
rename to frontends/nextjs/src/lib/schema/functions/record/filter-records.ts
diff --git a/frontends/nextjs/src/lib/schema/functions/get-records-key.ts b/frontends/nextjs/src/lib/schema/functions/record/get-records-key.ts
similarity index 100%
rename from frontends/nextjs/src/lib/schema/functions/get-records-key.ts
rename to frontends/nextjs/src/lib/schema/functions/record/get-records-key.ts
diff --git a/frontends/nextjs/src/lib/schema/functions/sort-records.ts b/frontends/nextjs/src/lib/schema/functions/record/sort-records.ts
similarity index 100%
rename from frontends/nextjs/src/lib/schema/functions/sort-records.ts
rename to frontends/nextjs/src/lib/schema/functions/record/sort-records.ts
diff --git a/frontends/nextjs/src/lib/schema/functions/validate-record.ts b/frontends/nextjs/src/lib/schema/functions/record/validate-record.ts
similarity index 100%
rename from frontends/nextjs/src/lib/schema/functions/validate-record.ts
rename to frontends/nextjs/src/lib/schema/functions/record/validate-record.ts