@flickfyi/flkr 0.0.182 → 0.0.185

package/node_modules/@flickfyi/core/src/kowalski/lesson.tsx

@@ -0,0 +1,564 @@
+import { Flex, Icon, Text } from '@flickfyi/core'
+import { Button as NativeButton } from '@flickfyi/core/atoms'
+import { Lesson as LessonEntity } from '@flickfyi/schemas/lesson'
+import * as stylex from '@stylexjs/stylex'
+import { type ReactNode, useState } from 'react'
+import { z } from 'zod/v4'
+
+import { buttonVars } from '~/atoms/button/button.stylex'
+import { useConfiguredFeature } from '~/hooks/use-configured-feature'
+import type { CreateSchemas } from '~/kowalski/create-schemas'
+import { size, space } from '~/themes/scale.stylex'
+import { appearance, button, roles } from '~/themes/shared'
+import { colors, shape } from '~/themes/tokens.stylex'
+
+import { entries, featureFields } from './feature-schema'
+import { format } from './format'
+import { FeatureAction, FeatureFrame, FeatureProgress, FeatureWell } from './frame'
+
+/**
+ * Teaches a lesson as a sequence of single-purpose screens. The overview names the lesson and
+ * the path of ideas with Start at the bottom. Learning shows only a progress bar and one thing:
+ * an idea to read, or a question about it with its answers as large tiles and the action at the
+ * bottom. Missed questions return in a review round with the idea retaught above them. The end
+ * screen leads with the score.
+ */
+const defaultId = 'KowalskiLesson'
+const defaultScope = 'private'
+
+export const LessonData = LessonEntity
+export type LessonData = LessonEntity
+
+export const LessonProps = z.strictObject({ data: LessonData, ...featureFields })
+export type LessonProps = z.input<typeof LessonProps> & {
+	style?: stylex.StyleXArray<stylex.StyleXStyles>
+}
+
+/** `result_<question id>` is "first" when right on the first try, "retry" after a miss, null when unanswered. */
+export const lessonStoreSchema = entries(
+	'result_',
+	z.enum(['first', 'retry']).nullable(),
+	{
+		missed: z.array(z.string()).default([]),
+		seen: z.array(z.string()).default([]),
+		started: z.boolean().default(false),
+	}
+)
+
+type Concept = LessonData['teaches'][number]
+type Question = LessonData['hasPart'][number]
+type Result = 'first' | 'retry' | null
+type TileState = 'correct' | 'dimmed' | 'idle' | 'missed' | 'selected' | 'wrong'
+
+export const createSchemas: CreateSchemas = ({
+	id = defaultId,
+	scope = defaultScope,
+} = {}) => ({
+	[`stores/${scope}/${id}`]: lessonStoreSchema,
+})
+
+export function Lesson({
+	data,
+	id = defaultId,
+	revision = 0,
+	scope = defaultScope,
+	style,
+}: LessonProps) {
+	const store = useConfiguredFeature({
+		name: id,
+		revision,
+		schema: lessonStoreSchema,
+		scope,
+		seed: lessonStoreSchema.parse({}),
+	})
+	const [selected, setSelected] = useState<string[]>([])
+	const [checked, setChecked] = useState(false)
+	const result = (question: Question): Result =>
+		store.value[`result_${question.id}`] ?? null
+	const seen = new Set(store.value.seen)
+	const missed = store.value.missed
+	const step = nextStep(data, seen, missed, result)
+	const total = data.teaches.length + data.hasPart.length
+	const done =
+		data.teaches.filter(concept => seen.has(concept.id)).length +
+		data.hasPart.filter(question => result(question) !== null).length
+	const ready = store.ready && !store.saving
+	const frame = (header: ReactNode, children: ReactNode) => (
+		<FeatureFrame
+			component="lesson"
+			header={header}
+			notice={store.error}
+			onRetry={store.retry}
+			style={style}
+			title={data.title}
+		>
+			{children}
+		</FeatureFrame>
+	)
+	const progress = (label: string, accent = true) => (
+		<Flex {...stylex.props(styles.bar)}>
+			<FeatureProgress component="lesson" value={total > 0 ? done / total : 0} />
+			<Text {...stylex.props(roles.caption, accent && appearance.accent)}>{label}</Text>
+		</Flex>
+	)
+
+	if (!store.value.started) {
+		return frame(
+			<Flex {...stylex.props(styles.title)}>
+				<Text {...stylex.props(roles.caption, appearance.accent)}>Lesson</Text>
+				<Text {...stylex.props(roles.h1)}>{data.title}</Text>
+			</Flex>,
+			<>
+				<Ideas data={data} result={result} seen={seen} />
+				<FeatureAction
+					component="lesson"
+					disabled={!ready || total === 0}
+					onClick={() => store.set(() => ({ started: true }))}
+					size="lg"
+					variant="primary"
+				>
+					{done > 0 ? 'Continue lesson' : 'Start lesson'}
+				</FeatureAction>
+			</>
+		)
+	}
+
+	if (step.kind === 'done') {
+		const first = data.hasPart.filter(question => result(question) === 'first').length
+		return frame(
+			<Flex {...stylex.props(styles.title)}>
+				<Text {...stylex.props(roles.caption, appearance.accent)}>Lesson complete</Text>
+				<Text {...stylex.props(roles.h2)}>{data.title}</Text>
+			</Flex>,
+			<>
+				<Flex {...stylex.props(styles.score)}>
+					<Text animated="numeric" {...stylex.props(roles.display)}>
+						{`${format.formatNumber(first)}/${format.formatNumber(data.hasPart.length)}`}
+					</Text>
+					<Text {...stylex.props(roles.muted)}>
+						{first === data.hasPart.length
+							? 'Every question right on the first try.'
+							: 'Right on the first try. Everything else you got on review.'}
+					</Text>
+				</Flex>
+				<FeatureAction
+					component="lesson"
+					disabled={!ready}
+					onClick={() =>
+						store.set(() => ({
+							...Object.fromEntries(
+								data.hasPart.map(question => [`result_${question.id}`, null])
+							),
+							missed: [],
+							seen: [],
+							started: false,
+						}))
+					}
+					variant="quiet"
+				>
+					Start over
+				</FeatureAction>
+			</>
+		)
+	}
+
+	if (step.kind === 'teach') {
+		const { concept } = step
+		return frame(
+			progress(
+				`Idea ${format.formatNumber(data.teaches.indexOf(concept) + 1)} of ${format.formatNumber(data.teaches.length)}`
+			),
+			<>
+				<Text {...stylex.props(roles.h1)}>{concept.name}</Text>
+				<Text {...stylex.props(roles.lead)}>{concept.description}</Text>
+				{concept.examples.length > 0 && (
+					<FeatureWell>
+						{concept.examples.map(example => (
+							<Flex key={example.name} {...stylex.props(styles.pair)}>
+								<Text {...stylex.props(roles.h2)}>{example.name}</Text>
+								<Text {...stylex.props(roles.muted)}>{example.value}</Text>
+							</Flex>
+						))}
+					</FeatureWell>
+				)}
+				<FeatureAction
+					component="lesson"
+					disabled={!ready}
+					onClick={() =>
+						store.set(current => ({ seen: [...new Set([...current.seen, concept.id])] }))
+					}
+					size="lg"
+					variant="primary"
+				>
+					Got it
+				</FeatureAction>
+			</>
+		)
+	}
+
+	const { question, review } = step
+	const concept = data.teaches.find(candidate => candidate.id === question.assesses)
+	const accepted = question.acceptedAnswer.map(answer => answer.text)
+	const flashcard = question.eduQuestionType === 'Flashcard'
+	const multiple = question.eduQuestionType === 'Checkbox'
+	const correct =
+		selected.length === accepted.length && selected.every(text => accepted.includes(text))
+	const wrong = question.suggestedAnswer.filter(answer => selected.includes(answer.text))
+	const answer = (right: boolean) => {
+		setSelected([])
+		setChecked(false)
+		if (right) {
+			store.set(current => ({
+				...Object.fromEntries([
+					[
+						`result_${question.id}`,
+						current.missed.includes(question.id) ? 'retry' : 'first',
+					],
+				]),
+				missed: current.missed.filter(id => id !== question.id),
+			}))
+		} else {
+			store.set(current => ({
+				missed: [...current.missed.filter(id => id !== question.id), question.id],
+			}))
+		}
+	}
+	const tileState = (option: string): TileState => {
+		const chosen = selected.includes(option)
+		if (!checked) {
+			return chosen ? 'selected' : 'idle'
+		}
+		if (accepted.includes(option)) {
+			return chosen ? 'correct' : 'missed'
+		}
+		return chosen ? 'wrong' : 'dimmed'
+	}
+	return frame(
+		progress(
+			review ? `Review · ${concept?.name ?? 'Practice'}` : (concept?.name ?? 'Practice')
+		),
+		<>
+			{review && concept && (
+				<Text {...stylex.props(roles.muted)}>{concept.description}</Text>
+			)}
+			<Flex {...stylex.props(styles.prompt)}>
+				<Text {...stylex.props(roles.h1)}>{question.text}</Text>
+				{multiple && !checked && (
+					<Text {...stylex.props(roles.muted)}>Choose every answer that applies.</Text>
+				)}
+			</Flex>
+			{flashcard ? (
+				checked && (
+					<Flex {...stylex.props(appearance.screen, styles.example)}>
+						<Text {...stylex.props(roles.caption)}>Answer</Text>
+						<Text {...stylex.props(roles.h1)}>
+							{format.formatList(accepted, { type: 'conjunction' })}
+						</Text>
+						{question.acceptedAnswer.map(item => (
+							<Text key={item.text} {...stylex.props(roles.text)}>
+								{item.answerExplanation}
+							</Text>
+						))}
+					</Flex>
+				)
+			) : (
+				<Flex {...stylex.props(styles.tiles)}>
+					{choices(question).map(option => (
+						<AnswerTile
+							key={option}
+							disabled={!store.ready}
+							label={option}
+							multiple={multiple}
+							state={tileState(option)}
+							onClick={() => {
+								if (checked) {
+									return
+								}
+								setSelected(current =>
+									multiple
+										? current.includes(option)
+											? current.filter(text => text !== option)
+											: [...current, option]
+										: [option]
+								)
+							}}
+						/>
+					))}
+				</Flex>
+			)}
+			{checked && !flashcard && (
+				<FeatureWell style={styles.feedback}>
+					<Flex {...stylex.props(styles.verdict)}>
+						<Icon
+							name={correct ? 'checkmark.circle.fill' : 'xmark.circle.fill'}
+							{...stylex.props(correct ? appearance.accent : styles.danger)}
+						/>
+						<Text
+							{...stylex.props(roles.h2, correct ? appearance.accent : styles.danger)}
+						>
+							{correct ? 'Correct' : 'Not quite'}
+						</Text>
+					</Flex>
+					{!correct && (
+						<Flex {...stylex.props(styles.pair)}>
+							<Text {...stylex.props(roles.caption)}>
+								{accepted.length > 1 ? 'Answers' : 'Answer'}
+							</Text>
+							{accepted.map(text => (
+								<Text key={text} {...stylex.props(roles.text, roles.strong)}>
+									{text}
+								</Text>
+							))}
+						</Flex>
+					)}
+					{!correct &&
+						wrong.flatMap(item =>
+							item.comment
+								? [
+										<Text key={item.text} {...stylex.props(roles.text, roles.strong)}>
+											{item.comment}
+										</Text>,
+									]
+								: []
+						)}
+					{question.acceptedAnswer.map(item => (
+						<Text key={item.text} {...stylex.props(roles.text)}>
+							{item.answerExplanation}
+						</Text>
+					))}
+				</FeatureWell>
+			)}
+			{flashcard && checked ? (
+				<Flex {...stylex.props(styles.grade)}>
+					<FeatureAction
+						component="lesson"
+						disabled={!ready}
+						onClick={() => answer(false)}
+						size="lg"
+					>
+						Not yet
+					</FeatureAction>
+					<FeatureAction
+						component="lesson"
+						disabled={!ready}
+						onClick={() => answer(true)}
+						size="lg"
+						variant="primary"
+					>
+						I knew it
+					</FeatureAction>
+				</Flex>
+			) : (
+				<FeatureAction
+					component="lesson"
+					disabled={!ready || (!flashcard && selected.length === 0)}
+					onClick={() => (checked ? answer(correct) : setChecked(true))}
+					size="lg"
+					variant="primary"
+				>
+					{checked ? 'Continue' : flashcard ? 'Show answer' : 'Check'}
+				</FeatureAction>
+			)}
+		</>
+	)
+}
+
+/** One answer as a full-width tile; after checking it shows right, wrong, or missed. */
+function AnswerTile({
+	disabled,
+	label,
+	multiple,
+	onClick,
+	state,
+}: {
+	disabled: boolean
+	label: string
+	multiple: boolean
+	onClick: () => void
+	state: TileState
+}) {
+	const icon =
+		state === 'correct' || state === 'missed'
+			? 'checkmark.circle.fill'
+			: state === 'wrong'
+				? 'xmark.circle.fill'
+				: multiple
+					? state === 'selected'
+						? 'checkmark.square.fill'
+						: 'square'
+					: undefined
+	return (
+		<NativeButton
+			accessibilityValue={
+				state === 'idle' || state === 'dimmed' ? 'Unselected' : 'Selected'
+			}
+			disabled={disabled}
+			onClick={onClick}
+			style={[
+				button.secondary,
+				styles.tile,
+				state === 'selected' && styles.selected,
+				state === 'correct' && styles.correct,
+				state === 'missed' && styles.missed,
+				state === 'wrong' && styles.wrong,
+				state === 'dimmed' && styles.dimmed,
+			]}
+		>
+			<Flex {...stylex.props(styles.tileRow)}>
+				<Text {...stylex.props(roles.text, styles.tileLabel)}>{label}</Text>
+				{icon && (
+					<Icon
+						name={icon}
+						{...stylex.props(
+							state === 'wrong'
+								? styles.danger
+								: state === 'idle'
+									? null
+									: appearance.accent
+						)}
+					/>
+				)}
+			</Flex>
+		</NativeButton>
+	)
+}
+
+/** What the lesson teaches, by name only; an idea is ticked once taught and practiced. */
+function Ideas({
+	data,
+	result,
+	seen,
+}: {
+	data: LessonData
+	result: (question: Question) => Result
+	seen: ReadonlySet<string>
+}) {
+	return (
+		<Flex {...stylex.props(styles.ideas)}>
+			<Text {...stylex.props(roles.caption)}>You’ll learn</Text>
+			{data.teaches.map(concept => {
+				const complete =
+					seen.has(concept.id) &&
+					data.hasPart.every(
+						question => question.assesses !== concept.id || result(question) !== null
+					)
+				return (
+					<Flex key={concept.id} {...stylex.props(styles.idea)}>
+						<Icon
+							name={complete ? 'checkmark.circle.fill' : 'circle'}
+							{...stylex.props(complete ? appearance.accent : appearance.mutedInk)}
+						/>
+						<Text {...stylex.props(roles.text)}>{concept.name}</Text>
+					</Flex>
+				)
+			})}
+		</Flex>
+	)
+}
+
+const styles = /* @__PURE__ */ stylex.create({
+	bar: { gap: space[2] },
+	// Unchosen answers sit quietly; a chosen answer takes the raised surface.
+	correct: {
+		[buttonVars.background]: colors.surface,
+		[buttonVars.border]: colors.accent,
+	},
+	danger: { color: colors.danger },
+	dimmed: { opacity: 0.45 },
+	example: { gap: space[1], padding: space[4] },
+	feedback: { alignItems: 'flex-start', gap: space[2] },
+	grade: { columnGap: space[2], flexDirection: 'row' },
+	idea: { alignItems: 'center', columnGap: space[2], flexDirection: 'row' },
+	ideas: { gap: space[2] },
+	missed: { [buttonVars.border]: colors.accent, borderStyle: 'dashed' },
+	selected: {
+		[buttonVars.background]: colors.surface,
+		[buttonVars.border]: colors.accent,
+	},
+	pair: { gap: space[0.5] },
+	prompt: { gap: space[2] },
+	score: { alignItems: 'flex-start', gap: space[1] },
+	tile: {
+		// Page sits between the tray and the surface's contrast in both modes, so unchosen answers
+		// stand off the tray while the chosen answer's surface stays the most prominent.
+		[buttonVars.background]: colors.page,
+		[buttonVars.border]: 'transparent',
+		alignItems: 'stretch',
+		borderRadius: shape.controlRadius,
+		minHeight: size[14],
+		paddingLeft: space[4],
+		paddingRight: space[4],
+		width: '100%',
+	},
+	tileLabel: { flexBasis: '0%', flexGrow: 1, minWidth: 0, textAlign: 'left' },
+	tileRow: {
+		alignItems: 'center',
+		columnGap: space[3],
+		flexDirection: 'row',
+		width: '100%',
+	},
+	tiles: { gap: space[2] },
+	title: { gap: space[1] },
+	verdict: { alignItems: 'center', columnGap: space[2], flexDirection: 'row' },
+	wrong: {
+		[buttonVars.background]: colors.surface,
+		[buttonVars.border]: colors.danger,
+		[buttonVars.text]: colors.danger,
+	},
+})
+
+/** Accepted and suggested answers mixed in an order that is stable for each question. */
+function choices(question: Question) {
+	const texts = [
+		...question.acceptedAnswer.map(answer => answer.text),
+		...question.suggestedAnswer.map(answer => answer.text),
+	]
+	return [...new Set(texts)].toSorted(
+		(a, b) => hash(`${question.id}:${a}`) - hash(`${question.id}:${b}`)
+	)
+}
+
+function hash(text: string) {
+	let value = 5381
+	for (const character of text) {
+		value = (value * 33 + (character.codePointAt(0) ?? 0)) % 2_147_483_647
+	}
+	return value
+}
+
+/** Concepts in order, each taught before its unanswered questions, then missed questions. */
+function nextStep(
+	data: LessonData,
+	seen: ReadonlySet<string>,
+	missed: readonly string[],
+	result: (question: Question) => Result
+):
+	| { concept: Concept; kind: 'teach' }
+	| { kind: 'question'; question: Question; review: boolean }
+	| { kind: 'done' } {
+	const pending = (question: Question) =>
+		result(question) === null && !missed.includes(question.id)
+	for (const concept of data.teaches) {
+		if (!seen.has(concept.id)) {
+			return { concept, kind: 'teach' }
+		}
+		const question = data.hasPart.find(
+			candidate => candidate.assesses === concept.id && pending(candidate)
+		)
+		if (question) {
+			return { kind: 'question', question, review: false }
+		}
+	}
+	// Questions whose concept is missing still get practiced, after every taught concept.
+	const known = new Set(data.teaches.map(concept => concept.id))
+	const orphan = data.hasPart.find(
+		question => !known.has(question.assesses) && pending(question)
+	)
+	if (orphan) {
+		return { kind: 'question', question: orphan, review: false }
+	}
+	const retry = missed.flatMap(id =>
+		data.hasPart.filter(question => question.id === id && result(question) === null)
+	)[0]
+	return retry ? { kind: 'question', question: retry, review: true } : { kind: 'done' }
+}