@classytic/labs 0.1.0

package/dist/physics/vector-board/preset.mjs

@@ -0,0 +1,273 @@
+'use client';
+
+import { toDeg } from "../../core/util.mjs";
+import { RichText } from "../../kit/rich.mjs";
+import { Callout, LabFrame, LiveRegion } from "../../kit/frame.mjs";
+import { Feedback, HintLadder, useCheckpoint, useHints } from "../../kit/pedagogy.mjs";
+import { AngleArc, LabeledVector, RightAngleMark } from "../../kit/diagram.mjs";
+import { Fragment, useEffect, useMemo, useState } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { Axes, Label, MovableDot, Segment, Stage, Vector, vec } from "@classytic/stage";
+
+//#region src/physics/vector-board/preset.tsx
+/**
+* VectorBoard — the GENERAL, authorable vector lab (CAIE/IGCSE).
+*
+* A creator declares vectors (tail, components, colour, label, draggable) + how
+* to combine them (`sum` → resultant, tip-to-tail / parallelogram; `diff` →
+* relative velocity, the rain / "V_RC = V_C − V_A" case) + an optional
+* drag-to-match goal. From this one board: resultant addition, component
+* resolution, river-crossing, walking-home, relative-velocity — all as DATA.
+*
+* Built entirely on @classytic/stage primitives (Vector, MovableDot, Axes, vec
+* math, useLearner) + the shared LabeledVector / AngleArc helpers — nothing
+* reinvented. Drag a head, watch the resultant + angle update; land it on the
+* target to solve.
+*/
+const ORIGIN = {
+	x: 0,
+	y: 0
+};
+const PALETTE = [
+	"var(--stage-accent)",
+	"var(--stage-accent-2)",
+	"var(--stage-good)"
+];
+/**
+* Frame the board to everything that matters — origin, every arrow tip, the
+* resultant, and the goal — with padding, snapped to integers for clean axes.
+* Computed from the AUTHORED vectors (not live drag state) so the view stays put
+* while the learner drags, and the resultant can never shoot off-frame.
+*/
+function autoView(vectors, combine, goal) {
+	const comps = vectors.map((v) => v.comp);
+	const pts = [ORIGIN];
+	vectors.forEach((v, i) => pts.push(vec.add(v.tail ?? ORIGIN, comps[i] ?? ORIGIN)));
+	if (combine === "diff") pts.push(vec.sub(comps[0] ?? ORIGIN, comps[1] ?? ORIGIN));
+	else if (combine !== "none") pts.push(comps.reduce((a, c) => vec.add(a, c), ORIGIN));
+	if (goal) pts.push(goal.match);
+	const xs = pts.map((p) => p.x);
+	const ys = pts.map((p) => p.y);
+	const pad = 1.6;
+	return {
+		xMin: Math.floor(Math.min(0, ...xs) - pad),
+		xMax: Math.ceil(Math.max(0, ...xs) + pad),
+		yMin: Math.floor(Math.min(0, ...ys) - pad),
+		yMax: Math.ceil(Math.max(0, ...ys) + pad)
+	};
+}
+function VectorBoardLab({ view: viewProp, vectors, combine = "sum", resultantLabel = "R", resultantColor = "var(--stage-warn)", show = {
+	angle: true,
+	magnitude: true
+}, goal, snap = 1, objectives, hints: hintList, title = "Vectors", prompt = "Drag the arrow heads.", height = 320 }) {
+	const [comps, setComps] = useState(() => vectors.map((v) => v.comp));
+	useEffect(() => {
+		setComps(vectors.map((v) => v.comp));
+	}, [vectors]);
+	const view = useMemo(() => viewProp ?? autoView(vectors, combine, goal), [
+		viewProp,
+		vectors,
+		combine,
+		goal
+	]);
+	const tailOf = (i) => vectors[i]?.tail ?? ORIGIN;
+	const tipOf = (i) => vec.add(tailOf(i), comps[i] ?? ORIGIN);
+	const snapV = (v) => snap ? Math.round(v / snap) * snap : v;
+	const resultant = useMemo(() => {
+		if (combine === "none" || comps.length === 0) return null;
+		if (combine === "diff") return vec.sub(comps[0] ?? ORIGIN, comps[1] ?? ORIGIN);
+		return comps.reduce((acc, c) => vec.add(acc, c), ORIGIN);
+	}, [comps, combine]);
+	const tol = goal?.tol ?? .45;
+	const solved = !!(goal && resultant && vec.dist(resultant, goal.match) <= tol);
+	const hints = useHints(hintList);
+	useCheckpoint({
+		solved,
+		activity: "vector-board",
+		hintsUsed: hints.count
+	});
+	const resMag = resultant ? vec.mag(resultant) : 0;
+	const resDeg = resultant ? Math.round(toDeg(vec.angle(resultant))) : 0;
+	const resColor = solved ? "var(--stage-good)" : resultantColor;
+	const showResultant = !!resultant && !(combine === "sum" && vectors.length === 1);
+	const misconception = goal && !solved && resultant && Math.abs(vec.mag(resultant) - vec.mag(goal.match)) < tol ? "Right length — now fix the direction (rotate it onto the target)." : void 0;
+	const figure = /* @__PURE__ */ jsxs(Stage, {
+		view,
+		height,
+		preserveAspect: true,
+		ariaLabel: `${title}; resultant magnitude ${resMag.toFixed(1)} at ${resDeg} degrees`,
+		children: [
+			/* @__PURE__ */ jsx(Axes, { labels: true }),
+			goal && /* @__PURE__ */ jsx(Vector, {
+				tail: ORIGIN,
+				tip: goal.match,
+				color: "var(--stage-good)",
+				weight: 2,
+				opacity: .28
+			}),
+			show.parallelogram && combine === "sum" && resultant && comps.length === 2 && /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(Segment, {
+				from: comps[0] ?? ORIGIN,
+				to: resultant,
+				color: "var(--stage-muted)",
+				dashed: true,
+				weight: 1.2,
+				opacity: .6
+			}), /* @__PURE__ */ jsx(Segment, {
+				from: comps[1] ?? ORIGIN,
+				to: resultant,
+				color: "var(--stage-muted)",
+				dashed: true,
+				weight: 1.2,
+				opacity: .6
+			})] }),
+			vectors.map((v, i) => {
+				const col = v.color ?? PALETTE[i % PALETTE.length];
+				const c = comps[i];
+				if (!c) return null;
+				const t = tailOf(i);
+				const magStr = vec.mag(c).toFixed(1);
+				const text = v.label ? show.magnitude ? `|${v.label}| = ${magStr}` : v.label : show.magnitude ? magStr : "";
+				const at = {
+					x: t.x + c.x * .62,
+					y: t.y + c.y * .62
+				};
+				const L = Math.hypot(c.x, c.y) || 1;
+				let pmx = -c.y / L, pmy = c.x / L;
+				const ref = resultant ?? {
+					x: c.x,
+					y: c.y
+				};
+				if (pmx * (ref.x - at.x) + pmy * (ref.y - at.y) > 0) {
+					pmx = -pmx;
+					pmy = -pmy;
+				}
+				const dx = pmx * 26;
+				const dy = -pmy * 26;
+				return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(LabeledVector, {
+					tail: t,
+					comp: c,
+					color: col
+				}), text && /* @__PURE__ */ jsx(Label, {
+					x: at.x,
+					y: at.y,
+					text,
+					color: col,
+					dx,
+					dy,
+					size: 12
+				})] }, v.id ?? i);
+			}),
+			resultant && /* @__PURE__ */ jsxs(Fragment$1, { children: [
+				show.components && /* @__PURE__ */ jsxs(Fragment$1, { children: [
+					/* @__PURE__ */ jsx(Segment, {
+						from: ORIGIN,
+						to: {
+							x: resultant.x,
+							y: 0
+						},
+						color: "var(--stage-muted)",
+						dashed: true,
+						weight: 1.2,
+						opacity: .7
+					}),
+					/* @__PURE__ */ jsx(Segment, {
+						from: {
+							x: resultant.x,
+							y: 0
+						},
+						to: resultant,
+						color: "var(--stage-muted)",
+						dashed: true,
+						weight: 1.2,
+						opacity: .7
+					}),
+					/* @__PURE__ */ jsx(RightAngleMark, {
+						at: {
+							x: resultant.x,
+							y: 0
+						},
+						u: {
+							x: -Math.sign(resultant.x || 1),
+							y: 0
+						},
+						v: {
+							x: 0,
+							y: Math.sign(resultant.y || 1)
+						}
+					})
+				] }),
+				showResultant && /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(LabeledVector, {
+					tail: ORIGIN,
+					comp: resultant,
+					color: resColor,
+					weight: 3.5
+				}), /* @__PURE__ */ jsx(Label, {
+					x: resultant.x,
+					y: resultant.y,
+					text: resultantLabel,
+					color: resColor,
+					dx: 12,
+					dy: -10,
+					size: 13
+				})] }),
+				show.angle && /* @__PURE__ */ jsx(AngleArc, {
+					at: ORIGIN,
+					from: {
+						x: 1,
+						y: 0
+					},
+					to: resultant,
+					label: `${Math.abs(resDeg)}°`
+				})
+			] }),
+			vectors.map((v, i) => v.drag ? /* @__PURE__ */ jsx(MovableDot, {
+				value: tipOf(i),
+				onMove: (p) => setComps((cs) => cs.map((c, j) => j === i ? {
+					x: snapV(p.x) - tailOf(i).x,
+					y: snapV(p.y) - tailOf(i).y
+				} : c)),
+				range: {
+					min: Math.min(view.xMin, view.yMin),
+					max: Math.max(view.xMax, view.yMax)
+				},
+				color: v.color ?? PALETTE[i % PALETTE.length],
+				ariaLabel: `${v.label ?? "vector"} head`
+			}, `d${v.id ?? i}`) : null)
+		]
+	});
+	return /* @__PURE__ */ jsx(LabFrame, {
+		title,
+		prompt,
+		objectives,
+		footer: /* @__PURE__ */ jsxs(Fragment$1, { children: [
+			/* @__PURE__ */ jsxs(Callout, {
+				tone: solved ? "result" : "info",
+				children: [/* @__PURE__ */ jsxs("span", {
+					style: {
+						fontWeight: 600,
+						fontVariantNumeric: "tabular-nums"
+					},
+					children: [
+						/* @__PURE__ */ jsx(RichText, { children: resultantLabel }),
+						" = ",
+						resMag.toFixed(1),
+						" @ ",
+						resDeg,
+						"°"
+					]
+				}), goal && /* @__PURE__ */ jsx(Feedback, {
+					ok: solved,
+					misconception,
+					okText: "On target",
+					tryText: "Match the target"
+				})]
+			}),
+			goal && /* @__PURE__ */ jsx(HintLadder, { hints }),
+			/* @__PURE__ */ jsx(LiveRegion, { children: goal ? solved ? "On target" : misconception ?? `Resultant ${resMag.toFixed(1)} at ${resDeg} degrees` : "" })
+		] }),
+		children: figure
+	});
+}
+
+//#endregion
+export { VectorBoardLab };

package/dist/physics/vector-board/view.d.mts

@@ -0,0 +1,49 @@
+import { ReactNode } from "react";
+
+//#region src/physics/vector-board/view.d.ts
+interface FlatVec {
+  label?: string;
+  dx?: number | string;
+  dy?: number | string;
+  color?: string;
+  drag?: boolean;
+}
+interface VectorBoardViewProps {
+  vectors?: FlatVec[];
+  combine?: 'sum' | 'diff' | 'none';
+  goalX?: number | string;
+  goalY?: number | string;
+  tol?: number;
+  components?: boolean;
+  angle?: boolean;
+  parallelogram?: boolean;
+  title?: string;
+  prompt?: string;
+  view?: {
+    xMin: number;
+    xMax: number;
+    yMin: number;
+    yMax: number;
+  };
+  resultantLabel?: string;
+  objectives?: string[];
+  hints?: string[];
+}
+declare function VectorBoardView({
+  vectors,
+  combine,
+  goalX,
+  goalY,
+  tol,
+  components,
+  angle,
+  parallelogram,
+  title,
+  prompt,
+  view,
+  resultantLabel,
+  objectives,
+  hints
+}: VectorBoardViewProps): ReactNode;
+//#endregion
+export { VectorBoardView };

package/dist/physics/vector-board/view.mjs

@@ -0,0 +1,58 @@
+'use client';
+
+import { VectorBoardLab } from "./preset.mjs";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/physics/vector-board/view.tsx
+/** Default vectors for a freshly-inserted block. */
+const VECTOR_BOARD_DEMO = [{
+	label: "a",
+	dx: 3,
+	dy: 1,
+	color: "var(--stage-accent)",
+	drag: true
+}, {
+	label: "b",
+	dx: 1,
+	dy: 2,
+	color: "var(--stage-accent-2)",
+	drag: true
+}];
+function VectorBoardView({ vectors, combine = "sum", goalX, goalY, tol, components, angle, parallelogram, title, prompt, view, resultantLabel, objectives, hints }) {
+	const vs = (vectors ?? []).map((v) => ({
+		comp: {
+			x: Number(v.dx) || 0,
+			y: Number(v.dy) || 0
+		},
+		label: v.label,
+		color: v.color || void 0,
+		drag: !!v.drag
+	}));
+	const goal = goalX !== void 0 && goalX !== "" && goalY !== void 0 && goalY !== "" ? {
+		match: {
+			x: Number(goalX) || 0,
+			y: Number(goalY) || 0
+		},
+		tol
+	} : void 0;
+	return /* @__PURE__ */ jsx(VectorBoardLab, {
+		view,
+		vectors: vs,
+		combine,
+		resultantLabel,
+		goal,
+		objectives,
+		hints,
+		show: {
+			components,
+			angle,
+			parallelogram,
+			magnitude: true
+		},
+		title: title ?? "Vectors",
+		prompt: prompt ?? (goal ? "Drag the heads so the resultant lands on the target." : "Drag the arrow heads.")
+	});
+}
+
+//#endregion
+export { VECTOR_BOARD_DEMO, VectorBoardView };

package/dist/physics/vector-scene.d.mts

@@ -0,0 +1,41 @@
+import { ReactNode } from "react";
+
+//#region src/physics/vector-scene.d.ts
+interface SceneVector {
+  id: string;
+  /** Base components (ignored if `combine` is set). */
+  dx?: number;
+  dy?: number;
+  /** Anchor the tail at another vector's tip (tip-to-tail); default = origin. */
+  from?: string;
+  /** Derived: components = of[0] (op) of[1]. */
+  combine?: {
+    op: 'add' | 'sub';
+    of: [string, string];
+  };
+  /** Drag the tip to set dx,dy (base vectors only). */
+  draggable?: boolean;
+  /** Show dashed x/y component decomposition. */
+  components?: boolean;
+  color?: string;
+  label?: string;
+}
+interface VectorSceneProps {
+  vectors?: SceneVector[];
+  view?: {
+    xMin: number;
+    xMax: number;
+    yMin: number;
+    yMax: number;
+  };
+  title?: string;
+  height?: number;
+}
+declare function VectorScene({
+  vectors,
+  view,
+  title,
+  height
+}?: VectorSceneProps): ReactNode;
+//#endregion
+export { SceneVector, VectorScene, VectorSceneProps };

package/dist/physics/vector-scene.mjs

@@ -0,0 +1,211 @@
+'use client';
+
+import { clamp, toDeg } from "../core/util.mjs";
+import { LabFrame } from "../kit/frame.mjs";
+import { LabeledVector } from "../kit/diagram.mjs";
+import { useEffect, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Axes, Dot, Grid, MovableDot, Stage } from "@classytic/stage";
+
+//#region src/physics/vector-scene.tsx
+/**
+* VectorScene — a GENERAL vector-algebra board (not one problem), now on the
+* @classytic/stage engine (SVG arrows, draggable tips, accessible).
+*
+* A creator declares named vectors; some are draggable (drag the tip to set
+* direction & magnitude), some are *derived* (sum or difference of others), and
+* any vector can be anchored tip-to-tail on another. The board shows the arrows,
+* optional dashed component (sin/cos) decomposition, and per-vector magnitude +
+* angle. One authored scene each = river crossing, rain-on-a-walker, relative
+* velocity, force balance, projectile components, … thousands of problems from
+* one tool.
+*
+*   <VectorScene vectors={[
+*     { id:'boat', dx:0, dy:4, draggable:true, label:'boat' },
+*     { id:'cur',  dx:2, dy:0, label:'current' },
+*     { id:'R', combine:{op:'add', of:['boat','cur']}, label:'resultant', components:true },
+*   ]} />
+*/
+const DEFAULT = [
+	{
+		id: "a",
+		dx: 3,
+		dy: 1,
+		draggable: true,
+		label: "a",
+		color: "var(--stage-accent)"
+	},
+	{
+		id: "b",
+		dx: 1,
+		dy: 3,
+		draggable: true,
+		label: "b",
+		color: "var(--stage-accent-2)"
+	},
+	{
+		id: "R",
+		combine: {
+			op: "add",
+			of: ["a", "b"]
+		},
+		label: "a + b",
+		color: "var(--stage-good)",
+		components: true
+	}
+];
+function resolveScene(vectors, overrides) {
+	const comp = /* @__PURE__ */ new Map();
+	const tail = /* @__PURE__ */ new Map();
+	const out = [];
+	for (const v of vectors) {
+		let c;
+		if (v.combine) {
+			const a = comp.get(v.combine.of[0]) ?? {
+				x: 0,
+				y: 0
+			};
+			const b = comp.get(v.combine.of[1]) ?? {
+				x: 0,
+				y: 0
+			};
+			c = v.combine.op === "sub" ? {
+				x: a.x - b.x,
+				y: a.y - b.y
+			} : {
+				x: a.x + b.x,
+				y: a.y + b.y
+			};
+		} else c = overrides[v.id] ?? {
+			x: v.dx ?? 0,
+			y: v.dy ?? 0
+		};
+		comp.set(v.id, c);
+		const anchor = v.from && tail.has(v.from) ? {
+			x: tail.get(v.from).x + comp.get(v.from).x,
+			y: tail.get(v.from).y + comp.get(v.from).y
+		} : {
+			x: 0,
+			y: 0
+		};
+		tail.set(v.id, anchor);
+		out.push({
+			id: v.id,
+			tail: anchor,
+			comp: c,
+			color: v.color ?? "var(--stage-accent)",
+			label: v.label,
+			components: v.components,
+			draggable: v.draggable && !v.combine
+		});
+	}
+	return out;
+}
+function autoView(vectors) {
+	const r = resolveScene(vectors, {});
+	const xs = [0], ys = [0];
+	for (const v of r) {
+		xs.push(v.tail.x, v.tail.x + v.comp.x);
+		ys.push(v.tail.y, v.tail.y + v.comp.y);
+	}
+	const pad = 1.5;
+	const span = Math.max(2, Math.max(...xs) - Math.min(...xs), Math.max(...ys) - Math.min(...ys));
+	const cx = (Math.max(...xs) + Math.min(...xs)) / 2, cy = (Math.max(...ys) + Math.min(...ys)) / 2;
+	const half = span / 2 + pad;
+	return {
+		xMin: cx - half,
+		xMax: cx + half,
+		yMin: cy - half,
+		yMax: cy + half
+	};
+}
+function VectorScene({ vectors, view, title = "Vectors", height = 340 } = {}) {
+	const vecs = vectors && vectors.length ? vectors : DEFAULT;
+	const [overrides, setOverrides] = useState({});
+	useEffect(() => {
+		setOverrides({});
+	}, [vecs.map((v) => `${v.id}:${v.dx},${v.dy}`).join("|")]);
+	const v = view ?? autoView(vecs);
+	const resolved = resolveScene(vecs, overrides);
+	const drawable = resolved.filter((r) => Math.hypot(r.comp.x, r.comp.y) > 1e-6);
+	const draggables = resolved.filter((r) => r.draggable);
+	const labelled = drawable.filter((r) => r.label);
+	const figure = /* @__PURE__ */ jsx("div", {
+		style: {
+			borderRadius: 14,
+			overflow: "hidden",
+			background: "var(--stage-bg)",
+			border: "1px solid var(--stage-grid)"
+		},
+		children: /* @__PURE__ */ jsxs(Stage, {
+			view: v,
+			height,
+			ariaLabel: `Vector diagram: ${drawable.map((r) => r.label ?? r.id).join(", ")}`,
+			children: [
+				/* @__PURE__ */ jsx(Grid, {}),
+				/* @__PURE__ */ jsx(Axes, {}),
+				/* @__PURE__ */ jsx(Dot, {
+					x: 0,
+					y: 0,
+					r: 3,
+					color: "var(--stage-fg)",
+					opacity: .6
+				}),
+				drawable.map((r) => /* @__PURE__ */ jsx(LabeledVector, {
+					tail: r.tail,
+					comp: r.comp,
+					color: r.color,
+					label: r.label,
+					components: r.components
+				}, r.id)),
+				draggables.map((r) => /* @__PURE__ */ jsx(MovableDot, {
+					value: {
+						x: r.tail.x + r.comp.x,
+						y: r.tail.y + r.comp.y
+					},
+					onMove: (p) => setOverrides((o) => ({
+						...o,
+						[r.id]: {
+							x: clamp(p.x - r.tail.x, -50, 50),
+							y: clamp(p.y - r.tail.y, -50, 50)
+						}
+					})),
+					color: r.color,
+					ariaLabel: `tip of vector ${r.label ?? r.id}`
+				}, `h-${r.id}`))
+			]
+		})
+	});
+	const aside = labelled.length > 0 ? /* @__PURE__ */ jsx("div", {
+		style: {
+			display: "grid",
+			gap: 4,
+			fontVariantNumeric: "tabular-nums",
+			fontWeight: 600
+		},
+		children: labelled.map((r) => {
+			const mag = Math.hypot(r.comp.x, r.comp.y);
+			const ang = toDeg(Math.atan2(r.comp.y, r.comp.x));
+			return /* @__PURE__ */ jsxs("span", {
+				style: { color: r.color },
+				children: [
+					r.label,
+					": ",
+					mag.toFixed(2),
+					" ∠ ",
+					ang.toFixed(0),
+					"°"
+				]
+			}, r.id);
+		})
+	}) : void 0;
+	return /* @__PURE__ */ jsx(LabFrame, {
+		title,
+		prompt: draggables.length > 0 ? "Drag a vector’s tip to change it — sums and components update live." : void 0,
+		aside,
+		children: figure
+	});
+}
+
+//#endregion
+export { VectorScene };

package/dist/physics/vector-types/index.d.mts

@@ -0,0 +1 @@
+import { TypePanel, VectorTypesLab, VectorTypesProps } from "./preset.mjs";

package/dist/physics/vector-types/preset.d.mts

@@ -0,0 +1,27 @@
+import { ReactNode } from "react";
+import { Vec2 } from "@classytic/stage";
+
+//#region src/physics/vector-types/preset.d.ts
+interface PanelVec {
+  tail?: Vec2;
+  comp: Vec2;
+  color?: string;
+  label?: string;
+}
+interface TypePanel {
+  name: string;
+  caption: string;
+  vectors?: PanelVec[];
+  /** Show a dot at the origin (null vector / position origin O). */
+  origin?: boolean;
+}
+interface VectorTypesProps {
+  types?: TypePanel[];
+  title?: string;
+}
+declare function VectorTypesLab({
+  types,
+  title
+}: VectorTypesProps): ReactNode;
+//#endregion
+export { TypePanel, VectorTypesLab, VectorTypesProps };