@lincyaw/addon-classroom 0.0.0-stage → 1.0.0-rc.2

package/src/client/QuestionItem.tsx

@@ -0,0 +1,106 @@
+import { Fragment, useState, useRef, useEffect, useMemo, useId } from 'react'
+import type { ReactNode } from 'react'
+import { useMessages } from '@lincyaw/host'
+import { MESSAGES } from '../domain/index.ts'
+import type { Question } from '../domain/index.ts'
+import type { AiAnswers } from './ai-answers.ts'
+import './style.css'
+import './QuestionItem.css'
+export default function QuestionItem(
+  props: {
+    question: Question & { id: string }
+    active: boolean
+    ai: AiAnswers
+  } & {
+    children?: ReactNode
+    className?: string
+    onDone?(): void
+    onCited?(): void
+    onToggleAnswered?(): void
+    onSend?(): void
+  },
+) {
+  const { question, active, ai } = props
+
+  const t = useMessages(MESSAGES)
+  const draft = props.ai.drafts.get(props.question.id)
+
+  return (
+    <>
+      <li className="pm-classroom-question" data-answered={question.answered ? '' : undefined}>
+        <strong>{question.name}</strong>
+        {t.colon}
+        {question.text}
+        {active ? (
+          <button
+            type="button"
+            className="pm-ui-button pm-ui-button--small"
+            onClick={(event) => {
+              props.onToggleAnswered?.()
+            }}
+          >
+            {question.answered ? t.questions.markUnanswered : t.questions.markAnswered}
+          </button>
+        ) : null}
+        {active && ai.provider && !question.reply && !draft ? (
+          <button
+            type="button"
+            className="pm-classroom-panel__ai pm-ui-button pm-ui-button--small"
+            title={t.questions.aiTitle(ai.provider)}
+            onClick={(event) => {
+              ai.draftReply(question.id, question)
+            }}
+          >
+            {t.questions.ai(ai.provider)}
+          </button>
+        ) : null}
+        {draft ? (
+          <div className="pm-classroom-panel__draft" data-state={draft.state}>
+            {draft.state === 'running' ? (
+              <p className="pm-classroom-status" role="status">
+                {t.questions.aiAnswering}
+              </p>
+            ) : draft.state === 'ready' ? (
+              <>
+                <p className="pm-classroom-status">{t.questions.aiDraft}</p>
+                <p className="pm-classroom-panel__answer">{draft.text}</p>
+              </>
+            ) : (
+              <p className="pm-classroom-error" role="alert">
+                {t.questions.aiFailed(draft.error ?? '')}
+              </p>
+            )}
+            <p className="pm-classroom-actions">
+              {draft.state === 'ready' ? (
+                <button
+                  type="button"
+                  className="pm-ui-button pm-ui-button--primary pm-ui-button--small"
+                  onClick={(event) => {
+                    props.onSend?.()
+                  }}
+                >
+                  {t.questions.send}
+                </button>
+              ) : null}
+              <button
+                type="button"
+                className="pm-ui-button pm-ui-button--small"
+                onClick={(event) => {
+                  ai.discard(question.id)
+                }}
+              >
+                {t.questions.discard}
+              </button>
+            </p>
+          </div>
+        ) : null}
+        {question.reply ? (
+          <p className="pm-classroom-reply">
+            {question.reply.provider ? t.questions.reply(question.reply.provider) : ''}
+            {question.reply.text}
+          </p>
+        ) : null}
+      </li>
+    </>
+  )
+}

package/src/client/ai-answers.ts

@@ -0,0 +1,29 @@
+import { useService } from '@lincyaw/host'
+import { ASK, errorMessage } from '@lincyaw/kernel'
+import { useEffect, useRef, useState } from 'react'
+import type { Question } from '../domain/index.ts'
+export interface Draft { state: 'running' | 'ready' | 'failed', text: string, error?: string, provider?: string, stop: AbortController }
+const plainReply = (text: string) => text.replace(/\[([^\]\n]+)\]\(presmium:\/\/[^)\s]+\)/g, '$1').trim()
+export function useAiAnswers() {
+  const ask = useService(ASK)
+  const [drafts, setDrafts] = useState(new Map<string, Draft>())
+  const current = useRef(drafts); current.current = drafts
+  const change = (id: string, draft?: Draft) => setDrafts(before => { const next = new Map(before); if (draft) next.set(id, draft); else next.delete(id); return next })
+  useEffect(() => () => current.current.forEach(d => d.stop.abort()), [])
+  function draftReply(id: string, question: Question): void {
+    if (!ask || current.current.has(id)) return
+    const stop = new AbortController()
+    const draft: Draft = { state: 'running', text: '', provider: ask.provider(), stop }
+    change(id, draft)
+    void (async () => {
+      let text = ''
+      try {
+        for await (const piece of ask.ask(question.text, { document: '', section: question.section, ...question.block ? { block: question.block } : {} }, stop.signal)) text += piece
+        if (!stop.signal.aborted) change(id, { ...draft, text: plainReply(text), state: text.trim() ? 'ready' : 'failed' })
+      } catch (error) { if (!stop.signal.aborted) change(id, { ...draft, state: 'failed', error: errorMessage(error) }) }
+    })()
+  }
+  function discard(id: string) { current.current.get(id)?.stop.abort(); change(id) }
+  return { offered: Boolean(ask), provider: ask?.provider(), drafts, draftReply, discard }
+}
+export type AiAnswers = ReturnType<typeof useAiAnswers>

package/src/client/browser-store.ts

@@ -0,0 +1,86 @@
+import { siteBase } from '@lincyaw/host'
+import type { ClassroomStore } from '@lincyaw/kernel'
+
+type Data = Record<string, Record<string, unknown>>
+
+function localStorageOrNone(): Storage | undefined {
+  try {
+    return window.localStorage
+  } catch {
+    return undefined
+  }
+}
+
+export function createBrowserStore(key: string, storage = localStorageOrNone()): ClassroomStore {
+  const listeners = new Map<string, Set<() => void>>()
+  const notify = (name?: string) => (name ? [listeners.get(name)] : [...listeners.values()]).forEach(set => set?.forEach(listener => listener()))
+  const read = (): Data => {
+    try {
+      return JSON.parse(storage?.getItem(key) ?? '{}') as Data ?? {}
+    } catch {
+      return {}
+    }
+  }
+  const change = (name: string, apply: (items: Record<string, unknown>) => void) => {
+    const data = read()
+    const items = data[name] ?? {}
+    apply(items)
+    data[name] = items
+    try {
+      storage?.setItem(key, JSON.stringify(data))
+    } catch {}
+    notify(name)
+  }
+  window.addEventListener('storage', (event) => {
+    if (event.key === key) notify()
+  })
+  return {
+    list: <T>(name: string) => Object.entries(read()[name] ?? {}).map(([id, value]) => ({ id, value: value as T })),
+    get: <T>(name: string, id: string) => read()[name]?.[id] as T | undefined,
+    put(name, id, value) {
+      change(name, items => items[id] = JSON.parse(JSON.stringify(value)))
+    },
+    remove(name, id) {
+      change(name, items => delete items[id])
+    },
+    subscribe(name, listener) {
+      let set = listeners.get(name)
+      if (!set) listeners.set(name, set = new Set())
+      set.add(listener)
+      return () => {
+        set.delete(listener)
+      }
+    },
+  }
+}
+
+/** Writes to both stores; reads the first, then the second. */
+export function layeredStore(first: ClassroomStore, second: ClassroomStore): ClassroomStore {
+  return {
+    list<T>(name: string) {
+      const items = new Map(second.list<T>(name).map(item => [item.id, item]))
+      for (const item of first.list<T>(name)) items.set(item.id, item)
+      return [...items.values()]
+    },
+    get: <T>(name: string, id: string) => first.get<T>(name, id) ?? second.get<T>(name, id),
+    put(name, id, value) {
+      second.put(name, id, value)
+      first.put(name, id, value)
+    },
+    remove(name, id) {
+      second.remove(name, id)
+      first.remove(name, id)
+    },
+    subscribe(name, listener) {
+      const stops = [first.subscribe(name, listener), second.subscribe(name, listener)]
+      return () => stops.forEach(stop => stop())
+    },
+  }
+}
+
+let kept: ClassroomStore | undefined
+
+export function browserStore(): ClassroomStore {
+  kept ??= createBrowserStore(`presmium.classroom:${new URL(siteBase(), location.href).pathname}`)
+  return kept
+}

package/src/client/composables.ts

@@ -0,0 +1,43 @@
+import { useService, useSessionSnapshot } from '@lincyaw/host'
+import { CLASSROOM_STORE, errorMessage } from '@lincyaw/kernel'
+import type { ClassroomStore, StoredItem } from '@lincyaw/kernel'
+import { useEffect, useMemo, useState } from 'react'
+import { browserStore, layeredStore } from './browser-store.ts'
+
+export function useParticipation() {
+  const { session, snapshot } = useSessionSnapshot()
+  const me = snapshot?.me
+  const status = snapshot?.status ?? 'idle'
+  const joined = status !== 'idle' && me !== undefined
+  return { session, snapshot, me, status, joined, presenter: joined && me?.role === 'presenter' }
+}
+export function useClassroomStore(): ClassroomStore | undefined { return useService(CLASSROOM_STORE) }
+
+/** Subscription snapshots are cached in state; a collection may return a fresh array on every list(). */
+export function useCollection<T>(store: () => ClassroomStore | undefined, name: string, parse: (value: unknown) => T | undefined): StoredItem<T>[] {
+  const current = store()
+  const [items, setItems] = useState<StoredItem<T>[]>([])
+  useEffect(() => {
+    const update = () => setItems((current?.list<unknown>(name) ?? []).flatMap(({ id, value }) => {
+      const record = parse(value)
+      return record === undefined ? [] : [{ id, value: record }]
+    }))
+    update()
+    return current?.subscribe(name, update)
+  }, [current, name, parse])
+  return items
+}
+export function useNoteStore() {
+  const { session, status, joined } = useParticipation()
+  const inClassroom = joined && status === 'active' && session?.personal !== undefined
+  const store = useMemo(() => inClassroom ? layeredStore(session!.personal!, browserStore()) : browserStore(), [inClassroom, session])
+  return { store, inClassroom }
+}
+export function useGuardedWrite() {
+  const [failure, setFailure] = useState('')
+  function write(action: () => void): boolean {
+    setFailure('')
+    try { action(); return true } catch (error) { setFailure(errorMessage(error)); return false }
+  }
+  return { failure, write }
+}

package/src/client/env.d.ts

@@ -0,0 +1,7 @@
+interface ImportMetaEnv {
+  BASE_URL: string
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}

package/src/client/ids.ts

@@ -0,0 +1,3 @@
+export function newId(): string {
+  return `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`
+}

package/src/client/index.ts

@@ -0,0 +1,4 @@
+export { browserStore, createBrowserStore, layeredStore } from './browser-store.ts'
+export { useClassroomStore, useCollection, useGuardedWrite, useNoteStore, useParticipation } from './composables.ts'
+export { newId } from './ids.ts'
+export { classroomPlugin } from './plugin.ts'

package/src/client/plugin.ts

@@ -0,0 +1,57 @@
+import { currentLocale, STATUS, TOOLBAR } from '@lincyaw/host'
+import { CLASSROOM_STORE, EXECUTOR, PRESENTER_PANELS, SESSION } from '@lincyaw/kernel'
+import type { ClassroomStore, PluginDefinition, Unsubscribe } from '@lincyaw/kernel'
+import { version } from '../../package.json'
+import { CLASSROOM_ID, classroomSummary, COLLECTIONS, MESSAGES, toAnswer, toPrediction, toPulseVote, toQuestion, toQuizState, toSectionNumbers, toSubmission } from '../domain/index.ts'
+import type { ClassroomSummary } from '../domain/index.ts'
+import ClassroomPanel from './ClassroomPanel.tsx'
+import ClassroomToolbar from './ClassroomToolbar.tsx'
+
+let cleanup: Unsubscribe[] = []
+
+function records<T>(store: ClassroomStore | undefined, name: string, parse: (value: unknown) => T | undefined): (T & { id: string })[] {
+  return (store?.list<unknown>(name) ?? []).flatMap(({ id, value }) => {
+    const record = parse(value)
+    return record === undefined ? [] : [{ ...record, id }]
+  })
+}
+
+export const classroomPlugin: PluginDefinition = {
+  manifest: {
+    id: CLASSROOM_ID,
+    name: { 'zh-CN': '课堂', en: 'Classroom' },
+    version,
+    kernel: '^1.0.0',
+    requires: [SESSION, CLASSROOM_STORE, EXECUTOR, TOOLBAR, PRESENTER_PANELS, STATUS].map(token => ({ token, optional: true })),
+  },
+  setup(ctx) {
+    const title = MESSAGES[currentLocale()].interaction
+    const summary = (): ClassroomSummary => {
+      const store = ctx.tryGet(CLASSROOM_STORE)
+      const snapshot = ctx.tryGet(SESSION)?.snapshot()
+      return classroomSummary({
+        status: snapshot?.status ?? 'idle',
+        participants: snapshot?.participants ?? [],
+        questions: records(store, COLLECTIONS.questions, toQuestion),
+        quizzes: records(store, COLLECTIONS.quizzes, toQuizState),
+        answers: records(store, COLLECTIONS.answers, toAnswer),
+        predictions: records(store, COLLECTIONS.predictions, toPrediction),
+        votes: records(store, COLLECTIONS.pulse, toPulseVote),
+        submissions: records(store, COLLECTIONS.submissions, toSubmission),
+        numbers: toSectionNumbers(ctx.config),
+      })
+    }
+    cleanup = [
+      // The toolbar button also mounts the notes beside the sections, once per page (ClassroomOverlays).
+      ctx.tryGet(TOOLBAR)?.register({ id: CLASSROOM_ID, title, component: ClassroomToolbar, order: 20 }),
+      ctx.tryGet(PRESENTER_PANELS)?.register({ id: CLASSROOM_ID, title, component: ClassroomPanel, order: 20 }),
+      ctx.tryGet(STATUS)?.register({ id: CLASSROOM_ID, read: summary }),
+    ].filter(stop => stop !== undefined)
+  },
+  dispose() {
+    cleanup.forEach(stop => stop())
+    cleanup = []
+  },
+}
+
+export default classroomPlugin

package/src/client/style.css

@@ -0,0 +1,44 @@
+.pm-classroom-card {
+  --pm-text-xs: 0.75em;
+  --pm-text-sm: 0.875em;
+  --pm-text-md: 0.9375em;
+
+  box-sizing: border-box;
+  margin: 0.75em 0;
+  padding: 0.75em 1em;
+  border: var(--pm-size-hairline) solid var(--pm-color-line);
+  border-radius: var(--pm-radius-card);
+  background: var(--pm-color-surface);
+  color: var(--pm-color-ink);
+  font-family: var(--pm-font-sans);
+  font-size: 0.9em;
+  line-height: 1.5;
+  text-align: left;
+}
+.pm-classroom-card p {
+  margin: 0.35em 0;
+}
+.pm-classroom-actions {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.5em;
+}
+.pm-classroom-card .pm-ui-textarea,
+.pm-note-spot .pm-ui-textarea {
+  width: 100%;
+}
+.pm-classroom-status {
+  color: var(--pm-color-muted);
+}
+.pm-classroom-error {
+  color: var(--pm-color-danger);
+}
+.pm-classroom-reply {
+  margin: 0.35em 0;
+  padding: 0.35em 0.75em;
+  border-left: var(--pm-size-rule) solid var(--pm-color-accent);
+  border-radius: 0 var(--pm-radius-small) var(--pm-radius-small) 0;
+  background: var(--pm-color-accent-soft);
+  white-space: pre-wrap;
+}

package/src/domain/config.ts

@@ -0,0 +1,25 @@
+export const CLASSROOM_ID = 'presmium.classroom'
+
+export const COLLECTIONS = {
+  quizzes: 'quizzes',
+  answers: 'answers',
+  submissions: 'submissions',
+  questions: 'questions',
+  pulse: 'pulse',
+  predictions: 'predictions',
+  notes: 'notes',
+} as const
+
+const STUDENT_AUDIENCE = 'student'
+
+export function isForStudents(section: { audience?: readonly string[] }): boolean {
+  return !section.audience?.length || section.audience.includes(STUDENT_AUDIENCE)
+}
+
+export type SectionNumbers = Readonly<Record<string, number>>
+
+export function toSectionNumbers(config: Record<string, unknown> | undefined): SectionNumbers {
+  const sections = config?.sections
+  if (typeof sections !== 'object' || sections === null || Array.isArray(sections)) return {}
+  return Object.fromEntries(Object.entries(sections).filter((entry): entry is [string, number] => Number.isInteger(entry[1])))
+}

package/src/domain/exercise.ts

@@ -0,0 +1,143 @@
+import type { RunRequest, RunResult } from '@lincyaw/kernel'
+import type { ClassroomMessages } from './messages.ts'
+import type { Place } from './place.ts'
+
+const MARKER = '@@presmium-check@@'
+const SUBMISSION = 'submission.py'
+const CHECKS = 'checks.py'
+
+const CHECK_PROGRAM = `import ast as _pm_ast, json as _pm_json
+
+def _pm_describe(error):
+    line = error.lineno if isinstance(error, SyntaxError) and error.filename == ${JSON.stringify(SUBMISSION)} else None
+    tb = error.__traceback__
+    while tb is not None:
+        if tb.tb_frame.f_code.co_filename == ${JSON.stringify(SUBMISSION)}:
+            line = tb.tb_lineno
+        tb = tb.tb_next
+    return {'type': type(error).__name__, 'message': str(error), 'line': line}
+
+def _pm_check():
+    with open(${JSON.stringify(SUBMISSION)}, encoding='utf-8') as f:
+        submission = f.read()
+    with open(${JSON.stringify(CHECKS)}, encoding='utf-8') as f:
+        checks = f.read()
+    scope = {'__name__': '__main__'}
+    try:
+        exec(compile(submission, ${JSON.stringify(SUBMISSION)}, 'exec'), scope)
+    except BaseException as error:
+        return {'error': _pm_describe(error), 'cases': []}
+    cases = []
+    for node in _pm_ast.parse(checks).body:
+        case = {'line': node.lineno, 'code': _pm_ast.get_source_segment(checks, node) or '', 'ok': True}
+        try:
+            exec(compile(_pm_ast.Module(body=[node], type_ignores=[]), ${JSON.stringify(CHECKS)}, 'exec'), scope)
+        except BaseException as error:
+            case['ok'] = False
+            case['error'] = _pm_describe(error)
+        cases.append(case)
+    return {'error': None, 'cases': cases}
+
+print('\\n${MARKER}' + _pm_json.dumps(_pm_check(), ensure_ascii=False))
+`
+
+export function checkRequest(code: string, checks: string, timeoutMs?: number): RunRequest {
+  return { lang: 'python', code: CHECK_PROGRAM, files: { [SUBMISSION]: code, [CHECKS]: checks }, ...timeoutMs ? { timeoutMs } : {} }
+}
+
+export interface CheckError {
+  type: string
+  message: string
+  line?: number
+  kind: string
+  hint: string
+}
+
+export interface CheckCase {
+  line: number
+  code: string
+  ok: boolean
+  error?: CheckError
+}
+
+export interface CheckReport {
+  status: 'passed' | 'failed' | 'error'
+  passed: number
+  total: number
+  cases: CheckCase[]
+  error?: CheckError
+  output: string
+}
+
+function typicalError(type: string, message: string, t: ClassroomMessages, line?: number): CheckError {
+  const { kind, hint } = t.exercise.typical[type] ?? { kind: type, hint: t.exercise.unknown }
+  return { type, message, ...line ? { line } : {}, kind, hint }
+}
+
+interface RawError { type: string, message: string, line?: number | null }
+interface RawReport {
+  error: RawError | null
+  cases: { line: number, code: string, ok: boolean, error?: RawError }[]
+}
+
+export function checkReport(result: RunResult, t: ClassroomMessages): CheckReport {
+  const checkError = (raw: RawError) => typicalError(raw.type, raw.message, t, raw.line ?? undefined)
+  const at = result.stdout.lastIndexOf(`\n${MARKER}`)
+  const output = at >= 0 ? result.stdout.slice(0, at) : result.stdout
+  const failed = (error: CheckError): CheckReport => ({ status: 'error', passed: 0, total: 0, cases: [], error, output })
+  if (result.timedOut) return failed(typicalError('Timeout', result.stderr.trim(), t))
+  let raw: RawReport | undefined
+  try {
+    if (at >= 0) raw = JSON.parse(result.stdout.slice(at + MARKER.length + 1)) as RawReport
+  } catch {}
+  if (!raw || !Array.isArray(raw.cases)) {
+    const { kind, hint } = t.exercise.unchecked
+    return failed({ type: 'Error', message: result.stderr.trim() || t.exercise.noResult, kind, hint })
+  }
+  if (raw.error) return failed(checkError(raw.error))
+  const cases = raw.cases.map(c => ({ line: c.line, code: c.code, ok: c.ok, ...c.error ? { error: checkError(c.error) } : {} }))
+  const passed = cases.filter(c => c.ok).length
+  return { status: passed === cases.length ? 'passed' : 'failed', passed, total: cases.length, cases, output }
+}
+
+export interface Submission extends Place {
+  exerciseId: string
+  participant: string
+  name: string
+  status: CheckReport['status']
+  passed: number
+  total: number
+  kinds: string[]
+  at: number
+}
+
+export function submissionId(exerciseId: string, participant: string): string {
+  return `${exerciseId}:${participant}`
+}
+
+export function reportKinds(report: CheckReport): string[] {
+  const errors = report.error ? [report.error] : report.cases.flatMap(c => (c.error ? [c.error] : []))
+  return [...new Set(errors.map(e => e.kind))]
+}
+
+export interface ExerciseTally {
+  submitted: number
+  passed: number
+  kinds: [kind: string, count: number][]
+}
+
+export function exerciseTally(submissions: Submission[]): ExerciseTally {
+  const counts = new Map<string, number>()
+  for (const kind of submissions.flatMap(s => s.kinds)) counts.set(kind, (counts.get(kind) ?? 0) + 1)
+  return {
+    submitted: submissions.length,
+    passed: submissions.filter(s => s.status === 'passed').length,
+    kinds: [...counts].sort((a, b) => b[1] - a[1]),
+  }
+}
+
+export function exerciseTallyText(tally: ExerciseTally, t: ClassroomMessages): string {
+  const { exercise, list, people } = t
+  const common = tally.kinds.map(([kind, n]) => `${kind} ${people(n)}`).join(list)
+  return exercise.tally(tally.submitted, tally.passed) + (common ? exercise.common(common) : '')
+}

package/src/domain/index.ts

@@ -0,0 +1,40 @@
+export { CLASSROOM_ID, COLLECTIONS, isForStudents, toSectionNumbers } from './config.ts'
+export type { SectionNumbers } from './config.ts'
+export {
+  acceptsAnswers,
+  answerId,
+  countedAnswers,
+  isCorrect,
+  lateAnswers,
+  optionLetter,
+  quizSwitched,
+  quizTally,
+} from './quiz.ts'
+export type { Answer, QuizState, QuizTally } from './quiz.ts'
+export {
+  checkReport,
+  checkRequest,
+  exerciseTally,
+  exerciseTallyText,
+  reportKinds,
+  submissionId,
+} from './exercise.ts'
+export type { CheckCase, CheckError, CheckReport, ExerciseTally, Submission } from './exercise.ts'
+export { toAnswer, toNote, toPrediction, toPulseVote, toQuestion, toQuizState, toSavedPrediction, toSubmission } from './records.ts'
+export { notesAt } from './notes.ts'
+export type { Note } from './notes.ts'
+export { isAuthorLabel, placeIndex, placeKey, placeText } from './place.ts'
+export type { Place } from './place.ts'
+export { MESSAGES } from './messages.ts'
+export type { ClassroomMessages } from './messages.ts'
+export { pulseTally, voteId } from './pulse.ts'
+export type { PulseVote } from './pulse.ts'
+export { predictionId, predictionTally } from './predict.ts'
+export type { Prediction, PredictionTally, SavedPrediction } from './predict.ts'
+export { questionsByPlace } from './questions.ts'
+export type { Question, QuestionGroup, QuestionReply } from './questions.ts'
+export { exerciseSource, optionList, quizSource } from './source.ts'
+export type { CodeSource, ExerciseSource, QuizSource } from './source.ts'
+export { classroomRows, classroomSummary, unansweredCount } from './summary.ts'
+export type { ClassroomRecords, ClassroomRows, ClassroomSummary, SummaryInput } from './summary.ts'
+export { latestPerParticipant } from './tally.ts'