@khorsheed/dsh-library 0.0.0-stage → 0.1.1

package/lib/types/client/views/lesson.d.ts

@@ -0,0 +1,42 @@
+/**
+ * A station's 讲义 as its own page (proposal library-lesson-page): pushed from
+ * the station's guide (打开讲义) or opened by itself once the coach has written
+ * them after 开始学这一站. The markdown splits at its `##` headings — one
+ * section per knowledge point — so the contents can jump between them and
+ * show each point's mastery; wide panes keep the contents beside the text.
+ * Also the station guide's lesson card (LessonCard).
+ *
+ * @module @khorsheed/dsh-library/client/views/lesson
+ */
+import { type ReactNode } from 'react';
+import type { LibraryResource, RoadmapNode } from '../../types.ts';
+import { type ViewProps } from '../ui.tsx';
+/** One `##` section of the 讲义; the text before the first heading is the opening. */
+interface LessonSection {
+    readonly id: string;
+    readonly title: string | undefined;
+    readonly body: string;
+}
+/** Split the markdown at its `##` headings (deeper headings stay inside their section). */
+export declare function lessonSections(text: string): LessonSection[];
+/** The 讲义 page. */
+export declare function LessonView({ p, projectId, resourceId, nodeId }: ViewProps & {
+    projectId: string;
+    resourceId: string;
+    nodeId: string;
+}): ReactNode;
+/**
+ * The station guide's lesson card: no 讲义 yet → 开始学这一站 (a draft in the
+ * conversation input; the coach writes the 讲义 when it is sent); asked and
+ * waiting → 正在备课 (the 讲义 page opens by itself when they land); written →
+ * the points with their mastery and 打开讲义.
+ */
+export declare function LessonCard({ p, projectId, resourceId, node, resource }: {
+    p: ViewProps['p'];
+    projectId: string;
+    resourceId: string;
+    node: RoadmapNode;
+    resource: LibraryResource | undefined;
+}): ReactNode;
+export {};
+//# sourceMappingURL=lesson.d.ts.map

package/lib/types/client/views/lesson.js

@@ -0,0 +1,146 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * A station's 讲义 as its own page (proposal library-lesson-page): pushed from
+ * the station's guide (打开讲义) or opened by itself once the coach has written
+ * them after 开始学这一站. The markdown splits at its `##` headings — one
+ * section per knowledge point — so the contents can jump between them and
+ * show each point's mastery; wide panes keep the contents beside the text.
+ * Also the station guide's lesson card (LessonCard).
+ *
+ * @module @khorsheed/dsh-library/client/views/lesson
+ */
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { MarkdownText } from '@deepseek-ai/dsh-client-ui-primitives';
+import { PanelHeader } from '@khorsheed/dsh-client-ui-panel-kit/src/client/index.ts';
+import { stationMastery } from "../../mastery.js";
+import { outcome, StateLine, useLoad, value, when } from "../ui.js";
+import css from '../LibraryPane.module.css';
+/** How long 正在备课 waits for the 讲义 before offering to ask again. */
+const PREPARE_PATIENCE_MS = 10 * 60_000;
+/** Split the markdown at its `##` headings (deeper headings stay inside their section). */
+export function lessonSections(text) {
+    const sections = [];
+    let title;
+    let lines = [];
+    const flush = () => {
+        const body = lines.join('\n').trim();
+        if (title !== undefined || body !== '')
+            sections.push({ id: `s${sections.length}`, title, body });
+    };
+    for (const line of text.replace(/^#\s+.*\n/, '').split('\n')) {
+        const heading = /^##\s+(.+?)\s*$/.exec(line);
+        if (heading === null) {
+            lines.push(line);
+            continue;
+        }
+        flush();
+        title = heading[1].replace(/[*_`]/g, '');
+        lines = [];
+    }
+    flush();
+    return sections;
+}
+/** The point a section heading names, by its title. */
+function pointOf(title, points) {
+    if (title === undefined)
+        return undefined;
+    const squash = (value) => value.replace(/\s/g, '').toLowerCase();
+    return points.find(point => squash(title).includes(squash(point.title)));
+}
+/** The station's points with their mastery, for the dots (empty while loading). */
+function useStationPoints(p, projectId, node) {
+    const rev = p.useStore(s => s.rev);
+    const assessments = useLoad(() => value(p.listAssessments(projectId)), [projectId, rev]);
+    const attempts = useLoad(() => value(p.listAttempts(projectId)), [projectId, rev]);
+    if (node === undefined)
+        return [];
+    return stationMastery(node, assessments.data?.assessments ?? [], attempts.data?.attempts ?? []).points;
+}
+/** The 讲义 page. */
+export function LessonView({ p, projectId, resourceId, nodeId }) {
+    const { t, actions, useStore } = p;
+    const rev = useStore(s => s.rev);
+    const loaded = useLoad(async () => {
+        const [detail, roadmaps] = await Promise.all([outcome(p.getProject(projectId)), value(p.getRoadmap(projectId, resourceId))]);
+        return { resource: detail.resources.find(candidate => candidate.id === resourceId), node: roadmaps.roadmap?.nodes.find(candidate => candidate.id === nodeId) };
+    }, [projectId, resourceId, nodeId, rev]);
+    const node = loaded.data?.node;
+    const points = useStationPoints(p, projectId, node);
+    const sections = useMemo(() => lessonSections(node?.notes?.text ?? ''), [node?.notes?.text]);
+    const [active, setActive] = useState();
+    const [notice, setNotice] = useState();
+    const refs = useRef(new Map());
+    const markdownLabels = useMemo(() => ({
+        code: { copyLabel: t('markdown.copy'), copiedLabel: t('markdown.copied') },
+        footnotes: t('markdown.footnotes'),
+    }), [t]);
+    const jump = (id) => {
+        setActive(id);
+        refs.current.get(id)?.scrollIntoView({ behavior: 'smooth', block: 'start' });
+    };
+    const ask = () => {
+        if (node === undefined)
+            return;
+        void p.bindTarget({ projectId, resourceId });
+        setNotice(p.primeConversation(t('prime.lessonAsk', { node: node.title })) ? t('lesson.asked') : t('notice.noConversation'));
+    };
+    const titled = sections.filter(section => section.title !== undefined);
+    return (_jsxs(_Fragment, { children: [_jsx(PanelHeader, { title: node === undefined ? t('lesson.title') : t('lesson.titleOf', { node: node.title }), meta: loaded.data?.resource?.title, onBack: () => { actions.pop(); }, backLabel: t('action.back'), moreLabel: t('action.more') }), _jsxs("div", { className: css.body, children: [_jsx(StateLine, { loaded: loaded, t: t }), node !== undefined && node.notes === undefined && _jsx("div", { className: css.muted, children: t('lesson.none') }), node?.notes !== undefined && (_jsxs("div", { className: css.lesson, children: [_jsxs("nav", { className: css.lessonToc, "aria-label": t('lesson.contents'), children: [_jsx("span", { className: css.lessonTocHead, children: t('lesson.contentsMeta', { count: String(points.length) }) }), sections.map((section, index) => {
+                                        const point = pointOf(section.title, points);
+                                        return (_jsxs("button", { type: "button", className: css.lessonTocItem, "aria-current": active === section.id ? 'true' : undefined, onClick: () => { jump(section.id); }, children: [_jsx("i", { className: css.lessonDot, "data-state": point?.state ?? 'none', "aria-hidden": "true" }), _jsx("span", { children: section.title ?? (index === 0 ? t('lesson.opening') : '') })] }, section.id));
+                                    }), _jsxs("div", { className: css.lessonTocActions, children: [_jsx("button", { type: "button", className: css.primary, onClick: () => { actions.replace({ view: 'node', projectId, resourceId, nodeId, tab: 'quiz' }); }, children: t('lesson.toQuiz') }), _jsx("button", { type: "button", className: css.ghost, onClick: ask, children: t('lesson.ask') })] })] }), _jsxs("article", { className: css.lessonBody, children: [_jsxs("div", { className: css.muted, children: [t('lesson.meta', { at: when(node.notes.updatedAt, t), count: String(titled.length) }), node.notes.revisions > 1 ? ` · ${t('lesson.revised', { n: String(node.notes.revisions - 1) })}` : ''] }), sections.map(section => (_jsxs("section", { ref: element => { if (element === null)
+                                            refs.current.delete(section.id);
+                                        else
+                                            refs.current.set(section.id, element); }, className: css.lessonSection, children: [section.title !== undefined && _jsx("h2", { className: css.lessonHeading, children: section.title }), _jsx(MarkdownText, { text: section.body, labels: markdownLabels })] }, section.id))), _jsxs("section", { className: css.stepBox, children: [_jsxs("span", { className: css.stepText, children: [_jsx("strong", { children: t('lesson.doneTitle') }), _jsx("span", { className: css.muted, children: t('lesson.doneHint', { count: String(points.length) }) })] }), _jsxs("div", { className: css.askActions, children: [_jsx("button", { type: "button", className: css.ghost, onClick: ask, children: t('lesson.ask') }), _jsx("button", { type: "button", className: css.primary, onClick: () => { actions.replace({ view: 'node', projectId, resourceId, nodeId, tab: 'quiz' }); }, children: t('lesson.toQuiz') })] })] }), notice !== undefined && _jsx("div", { className: css.notice, children: notice })] })] }))] })] }));
+}
+/**
+ * The station guide's lesson card: no 讲义 yet → 开始学这一站 (a draft in the
+ * conversation input; the coach writes the 讲义 when it is sent); asked and
+ * waiting → 正在备课 (the 讲义 page opens by itself when they land); written →
+ * the points with their mastery and 打开讲义.
+ */
+export function LessonCard({ p, projectId, resourceId, node, resource }) {
+    const { t, actions, useStore } = p;
+    const key = `${projectId}:${resourceId}:${node.id}`;
+    const since = useStore(s => s.preparing[key]);
+    const points = useStationPoints(p, projectId, node);
+    const [failed, setFailed] = useState(false);
+    const [now, setNow] = useState(Date.now());
+    const notes = node.notes;
+    // Waiting: re-read now and then; the page opens itself once the 讲义 land.
+    useEffect(() => {
+        if (since === undefined)
+            return;
+        if (notes !== undefined && Date.parse(notes.updatedAt) >= since) {
+            actions.setPreparing(key, undefined);
+            actions.push({ view: 'lesson', projectId, resourceId, nodeId: node.id });
+            return;
+        }
+        const timer = setInterval(() => { setNow(Date.now()); actions.refresh(); }, 4000);
+        return () => { clearInterval(timer); };
+    }, [since, notes?.updatedAt]);
+    const start = () => {
+        void p.bindTarget({ projectId, resourceId });
+        const text = t(resource?.origin === 'authored' ? 'prime.lessonStart' : 'prime.lessonStartBook', {
+            book: resource?.title ?? '',
+            node: node.title,
+            points: (node.points ?? []).map(point => point.title).join('、'),
+        });
+        if (!p.primeConversation(text)) {
+            setFailed(true);
+            return;
+        }
+        setFailed(false);
+        actions.setPreparing(key, Date.now());
+    };
+    const ask = () => {
+        void p.bindTarget({ projectId, resourceId });
+        if (!p.primeConversation(t('prime.lessonAsk', { node: node.title })))
+            setFailed(true);
+    };
+    const waiting = since !== undefined && notes === undefined;
+    const stale = waiting && now - since > PREPARE_PATIENCE_MS;
+    return (_jsxs("section", { className: css.stepBox, "data-lesson": "true", children: [notes === undefined ? (_jsxs(_Fragment, { children: [_jsxs("span", { className: css.stepText, children: [_jsx("strong", { children: waiting ? (stale ? t('lesson.prepareStale') : t('lesson.preparing')) : t('lesson.notReady') }), _jsx("span", { className: css.muted, children: waiting ? t('lesson.preparingHint') : t('lesson.notReadyHint') })] }), _jsxs("div", { className: css.askActions, children: [waiting && !stale
+                                ? _jsx("button", { type: "button", className: css.textButton, onClick: () => { actions.setPreparing(key, undefined); }, children: t('lesson.cancelWait') })
+                                : _jsx("button", { type: "button", className: css.ghost, onClick: ask, children: t('lesson.ask') }), _jsx("button", { type: "button", className: css.primary, disabled: waiting && !stale, onClick: start, children: t('lesson.start') })] })] })) : (_jsxs(_Fragment, { children: [_jsxs("span", { className: css.stepText, children: [_jsx("strong", { children: t('lesson.ready', { count: String((node.points ?? []).length) }) }), _jsx("span", { className: css.muted, children: t('lesson.meta', { at: when(notes.updatedAt, t), count: String(lessonSections(notes.text).filter(section => section.title !== undefined).length) }) }), points.length > 0 && (_jsx("span", { className: css.lessonPoints, children: points.map(point => _jsxs("span", { children: [_jsx("i", { className: css.lessonDot, "data-state": point.state, "aria-hidden": "true" }), point.title] }, point.id)) }))] }), _jsxs("div", { className: css.askActions, children: [_jsx("button", { type: "button", className: css.ghost, onClick: ask, children: t('lesson.ask') }), _jsx("button", { type: "button", className: css.primary, onClick: () => { actions.push({ view: 'lesson', projectId, resourceId, nodeId: node.id }); }, children: t('lesson.open') })] })] })), failed && _jsx("span", { className: css.muted, children: t('notice.noConversation') })] }));
+}

package/lib/types/client/views/path.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A textbook's adopted path as a vertical lesson rail (proposal
+ * library-slimming §5, option A): one row per station with its full title,
+ * a disc that says where the learner stands, and its knowledge points as
+ * mastery dots. Rows group under the contents' parts. Nothing is locked
+ * (D6): the next station — the first not yet passed — is only highlighted
+ * and opens its card (开始学 / 接着学 / 去订正).
+ *
+ * @module @khorsheed/dsh-library/client/views/path
+ */
+import type { ReactNode } from 'react';
+import { type LibraryStationMastery } from '../../mastery.ts';
+import { type LibraryResource, type LibraryRoadmap, type RoadmapNode } from '../../types.ts';
+import { type ViewProps } from '../ui.tsx';
+/** Where the learner stands on one station. */
+export type StationStatus = 'done' | 'studying' | 'ready' | 'todo';
+/**
+ * Passed (done) → 已过关; 讲义 written and the learner has been quizzed or has
+ * a weak point → 学习中; 讲义 written → 已备课; nothing yet → 未开始.
+ */
+export declare function stationStatus(node: RoadmapNode, mastery: LibraryStationMastery): StationStatus;
+/** The rail. */
+export declare function Path({ p, projectId, resource, roadmap, onOpen, onLesson, onRetake }: {
+    p: ViewProps['p'];
+    projectId: string;
+    resource: LibraryResource;
+    roadmap: LibraryRoadmap;
+    onOpen: (node: RoadmapNode) => void;
+    onLesson: (node: RoadmapNode) => void;
+    onRetake: (node: RoadmapNode) => void;
+}): ReactNode;
+//# sourceMappingURL=path.d.ts.map

package/lib/types/client/views/path.js

@@ -0,0 +1,64 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { stationMastery } from "../../mastery.js";
+import { coverKind, parseLocator } from "../../types.js";
+import { IconCheckOutlineMedium } from "../icons.js";
+import { Segments, useLoad, value } from "../ui.js";
+import { stationTitle } from "../titles.js";
+import css from '../LibraryPane.module.css';
+/**
+ * Passed (done) → 已过关; 讲义 written and the learner has been quizzed or has
+ * a weak point → 学习中; 讲义 written → 已备课; nothing yet → 未开始.
+ */
+export function stationStatus(node, mastery) {
+    if (node.state === 'done')
+        return 'done';
+    const tried = (node.quizStats?.attempts ?? 0) > 0 || mastery.open.length > 0 || mastery.points.some(point => point.state !== 'untested');
+    if (tried)
+        return 'studying';
+    return node.notes === undefined ? 'todo' : 'ready';
+}
+/** The contents part a station's first row sits under, when the contents has parts. */
+function partOf(node, resource) {
+    const cover = node.covers.find(candidate => coverKind(candidate) === 'resource' && candidate.ref === resource.id && candidate.locator !== undefined);
+    const first = cover?.locator === undefined ? undefined : parseLocator(cover.locator)[0]?.from;
+    return first === undefined ? undefined : resource.toc?.find(row => row.n === first)?.part;
+}
+/** The station's rows as a short label (第 3 章 / 第 3–4 章). */
+function rowsLabel(node, resource, t) {
+    const cover = node.covers.find(candidate => coverKind(candidate) === 'resource' && candidate.ref === resource.id && candidate.locator !== undefined);
+    return cover?.locator === undefined ? undefined : t('path.rows', { rows: cover.locator.replace(/-/g, '–') });
+}
+/** The rail. */
+export function Path({ p, projectId, resource, roadmap, onOpen, onLesson, onRetake }) {
+    const { t, useStore } = p;
+    const rev = useStore(s => s.rev);
+    const assessments = useLoad(() => value(p.listAssessments(projectId)), [projectId, rev]);
+    const attempts = useLoad(() => value(p.listAttempts(projectId)), [projectId, rev]);
+    const rows = roadmap.nodes.map(node => {
+        const mastery = stationMastery(node, assessments.data?.assessments ?? [], attempts.data?.attempts ?? []);
+        return { node, mastery, status: stationStatus(node, mastery) };
+    });
+    const levels = rows.filter(row => row.node.gate !== 'read');
+    const passed = levels.filter(row => row.status === 'done').length;
+    const allPoints = rows.flatMap(row => row.mastery.points);
+    const mastered = allPoints.filter(point => point.state === 'mastered').length;
+    // The recommended next station: the first level not yet passed.
+    const next = levels.find(row => row.status !== 'done')?.node.id;
+    let lastPart;
+    let number = 0;
+    return (_jsxs("section", { className: css.section, children: [_jsxs("div", { className: css.railHead, children: [_jsxs("span", { className: css.railCounts, children: [_jsxs("span", { children: [_jsx("b", { children: passed }), " / ", levels.length, " ", t('path.stationsPassed')] }), allPoints.length > 0 && _jsxs("span", { children: [_jsx("b", { children: mastered }), " / ", allPoints.length, " ", t('path.pointsMastered')] })] }), _jsx(Segments, { done: passed, total: levels.length, label: t('path.progress', { done: String(passed), total: String(levels.length) }) })] }), _jsx("ol", { className: css.rail, children: rows.map(({ node, mastery, status }) => {
+                    const part = partOf(node, resource);
+                    const showPart = part !== undefined && part !== lastPart;
+                    lastPart = part ?? lastPart;
+                    const side = node.gate === 'read';
+                    if (!side)
+                        number += 1;
+                    const isNext = node.id === next;
+                    const best = node.quizStats?.bestRatio;
+                    const open = mastery.open.length;
+                    return (_jsxs("li", { className: css.railItem, "data-status": status, "data-side": side ? 'true' : undefined, "data-next": isNext ? 'true' : undefined, children: [showPart && _jsx("span", { className: css.railPart, children: part }), _jsxs("div", { className: css.railRow, children: [_jsx("button", { type: "button", className: css.railDisc, "data-status": status, "data-next": isNext ? 'true' : undefined, "aria-label": node.title, onClick: () => { onOpen(node); }, children: status === 'done' ? _jsx(IconCheckOutlineMedium, { size: 18 }) : side ? '·' : number }), _jsxs("div", { className: css.railBody, children: [_jsx("button", { type: "button", className: css.railTitle, onClick: () => { onOpen(node); }, children: stationTitle(node.title) }), _jsxs("span", { className: css.railMeta, children: [status === 'done' && _jsx("span", { className: css.railState, "data-status": "done", children: best === undefined ? t('path.done') : t('path.doneBest', { percent: String(Math.round(best * 100)) }) }), status === 'studying' && _jsx("span", { className: css.railState, "data-status": "studying", children: open > 0 ? t('path.studyingOpen', { count: String(open) }) : t('path.studying') }), status === 'ready' && _jsx("span", { className: css.railState, "data-status": "ready", children: t('path.ready') }), rowsLabel(node, resource, t) !== undefined && _jsx("span", { children: rowsLabel(node, resource, t) }), mastery.points.length > 0 && (_jsx("span", { className: css.railDots, "aria-label": t('path.dotsLabel'), children: mastery.points.map(point => _jsx("i", { className: css.lessonDot, "data-state": point.state, title: `${point.title} · ${t(`point.${point.state}`)}` }, point.id)) }))] }), isNext && (_jsxs("span", { className: css.railNext, children: [_jsx("span", { className: css.muted, children: t(status === 'todo' ? 'path.nextTodo' : 'path.nextHint') }), _jsxs("span", { className: css.btnRow, children: [open > 0 && _jsx("button", { type: "button", className: css.ghost, onClick: () => { onRetake(node); }, children: t('path.retake', { count: String(open) }) }), _jsx("button", { type: "button", className: css.primary, onClick: () => { if (node.notes === undefined)
+                                                                    onOpen(node);
+                                                                else
+                                                                    onLesson(node); }, children: t(node.notes === undefined ? 'lesson.start' : 'path.continue') })] })] }))] })] })] }, node.id));
+                }) })] }));
+}

package/lib/types/client/views/quiz.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The chapter quiz in the sidebar, its result, and the daily review.
+ *
+ * A quiz is answered here: choice and fill questions are judged on the spot
+ * against the answer key; open questions are collected and handed to the
+ * coach, who judges them and ledgers the whole sitting (one attempt per
+ * sitting). A sitting with no open question is ledgered from here directly.
+ * 「这题有问题」 voids a question — it counts for nothing.
+ *
+ * Review is flashcards over the due cards: front, flip, self-rate. It moves
+ * only the schedule — never a node, never weakness.
+ *
+ * @module @khorsheed/dsh-library/client/views/quiz
+ */
+import { type ReactNode } from 'react';
+import { type LibraryAssessResult } from '../../types.ts';
+import { type ViewProps } from '../ui.tsx';
+/** The quiz screen: the whole paper on one scroll — every question numbered, judged on the spot, 交卷 once all are answered. The in-progress sitting persists locally (quiz-drafts) — leaving the paper never loses an answer. */
+export declare function QuizView({ p, projectId, resourceId, quizId }: ViewProps & {
+    projectId: string;
+    resourceId: string | undefined;
+    quizId: string;
+}): ReactNode;
+/** The sitting's result: the score, what unlocked, how the cards moved — and the loop's next step, which rides the conversation from here (a retake of the misses or a fresh set), so the flow never dead-ends on the score. */
+export declare function ResultView({ p, projectId, resourceId, result }: ViewProps & {
+    projectId: string;
+    resourceId: string | undefined;
+    result: LibraryAssessResult;
+}): ReactNode;
+/**
+ * Daily review as answering, not looking (M4): each due card is asked the
+ * way that fits it — a word as a cloze over its own sentence or a choice of
+ * its meaning against the learner's other glosses, a well-known word as a
+ * spelling, a concept as a one-line explanation checked against the answer.
+ * The pane judges what it can and maps it to the schedule (first try →
+ * recalled, after a hint → fuzzy, missed → forgot); concepts are self-rated.
+ * 「翻卡」 in the header falls back to the plain flashcard.
+ */
+export declare function ReviewView({ p, projectId }: ViewProps & {
+    projectId?: string;
+}): ReactNode;
+//# sourceMappingURL=quiz.d.ts.map