@beanchain/handbook-lms 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to `@beanchain/handbook-lms` are documented here.
+
+## [0.2.0] - 2026-02-23
+
+- Added strict domain-agnostic config module (`/config`) with `defineHandbookLmsConfig`.
+- Added expanded adapter contract (`/adapter`) for curriculum CRUD/reorder and review workflows.
+- Added headless hooks (`/react-headless`) for curriculum editor, learner review, and learner learning workspace state.
+- Added prebuilt MUI components (`/react-mui`) for curriculum editing, learner review, and learner learning workspaces.
+- Added canonical `contracts` zod schema surface for LMS entities and mutation payloads.
+- Added adapter-boundary schema validation in host adapters to enforce canonical payloads at runtime.
+- Parity pass: added module drag-and-drop reordering, slug-mode controls, markdown stage editing, and review follow-up history/diff UX in shared MUI components.
+- Learning parity pass: added shared multi-stage stepper, autosave markdown responses, mobile module drawer, and follow-up assignment diff/submit UX.
+- Added optional `notifications` callbacks for package editor/review/learning workspaces so host apps can plug in their own toast/notification systems.
+- Added strict UI config keys for learning autosave notices (`labels.autosaveNotice`, `workflow.enableAutosaveNotifications`, `workflow.autosaveNotificationCooldownMs`).
+- Expanded canonical core LMS types to include learning summaries, assignments, and mutation payloads.
+- Added integration tests for Team Courses and Solution Seeking wrapper pages consuming package editor/review components.
+- Documented provider-agnostic SQL setup with Supabase appendix guidance.
+
+## [0.1.0] - 2026-02-23
+
+- Initial package scaffold with `core`, `react`, `contracts`, and `sql` modules.
+- Added LMS adapter interface for host apps.
+- Added reusable course library React component.
+- Added `tsup` build pipeline for compiled JS + type declarations in `dist/`.

package/README.md

@@ -0,0 +1,149 @@
+# @beanchain/handbook-lms
+
+Reusable package for Handbook LMS logic.
+
+## Modules
+
+- `@beanchain/handbook-lms/core`: Canonical LMS types, schemas, and shared contracts.
+- `@beanchain/handbook-lms/adapter`: Adapter interfaces for host data integration.
+- `@beanchain/handbook-lms/config`: Strict UI config contract and `defineHandbookLmsConfig` helper.
+- `@beanchain/handbook-lms/react-headless`: Headless editor/review/learning hooks.
+- `@beanchain/handbook-lms/react-mui`: Prebuilt MUI editor/review/learning components.
+- `@beanchain/handbook-lms/react`: Legacy provider + headless course library component.
+- `@beanchain/handbook-lms/contracts`: HTTP endpoint constants and helpers.
+- `@beanchain/handbook-lms/sql`: Provider-agnostic DB guidance + Supabase appendix.
+
+## Canonical contracts
+
+Use `@beanchain/handbook-lms/contracts` for canonical runtime schemas:
+
+- Entity schemas: course, section/module/stage/question hierarchy, progress, assignments, learning summary.
+- Mutation schemas: curriculum CRUD payloads, reorder payloads, review payloads, assignment update payloads.
+
+These schemas are intended for adapter-boundary validation only. Package hooks/components assume canonical data and should not receive domain-specific field names.
+
+## Adapter boundary pattern
+
+Validate requests/responses in host adapters before crossing the package boundary:
+
+```ts
+import {
+  handbookLmsSectionListSchema,
+  handbookLmsReviewModuleInputSchema
+} from "@beanchain/handbook-lms/contracts";
+
+const curriculum = handbookLmsSectionListSchema.parse(await apiFetch("/api/lms-courses/.../curriculum"));
+const reviewPayload = handbookLmsReviewModuleInputSchema.parse(input);
+```
+
+If your backend uses different naming, map to canonical package fields in the adapter (for example `target_exercise_ids -> target_question_ids`).
+
+## Host app setup checklist
+
+- Implement `HandbookLmsAdapter` per domain (`team courses`, `solution seeking`, etc.).
+- Define strict UI config with `defineHandbookLmsConfig`.
+- Keep backend endpoints + database migrations in host repo.
+- Pass only canonical models into package hooks/components.
+- Optionally pass `notifications` callbacks into package UI components to integrate host-level toast systems.
+
+## UI config reference
+
+All keys in `HandbookLmsUiConfig` are required and strongly typed.
+
+Autosave notification keys:
+
+- `labels.autosaveNotice`: Message used for autosave success notices.
+- `workflow.enableAutosaveNotifications`: Enables/disables autosave notices from learning workspace.
+- `workflow.autosaveNotificationCooldownMs`: Minimum interval between autosave notices.
+
+Recommended defaults:
+
+- `workflow.enableAutosaveNotifications: true`
+- `workflow.autosaveNotificationCooldownMs: 12000`
+- `labels.autosaveNotice: "Progress autosaved."`
+
+Example:
+
+```ts
+import { defineHandbookLmsConfig } from "@beanchain/handbook-lms/config";
+
+export const lmsConfig = defineHandbookLmsConfig({
+  labels: {
+    editorTitle: "Course Editor",
+    reviewTitle: "Course Review",
+    backButton: "Back",
+    addSection: "Add section",
+    addModule: "Add module",
+    addStage: "Add stage",
+    addQuestion: "Add question",
+    editAction: "Edit",
+    archiveAction: "Archive",
+    restoreAction: "Restore",
+    saveAction: "Save",
+    cancelAction: "Cancel",
+    saveResponseAction: "Save response",
+    submitModuleAction: "Submit module",
+    passAction: "Mark passed",
+    requestRevisionAction: "Request revision",
+    applyStatusAction: "Apply status",
+    noModulesMessage: "No modules are currently configured.",
+    autosaveNotice: "Progress autosaved."
+  },
+  workflow: {
+    enableModuleDragAndDrop: true,
+    enableStatusOverride: true,
+    enableFollowUpAssignments: true,
+    enableTargetedQuestionSelection: true,
+    enableAutosaveNotifications: true,
+    autosaveNotificationCooldownMs: 12000
+  },
+  validation: {
+    slugPattern: /^[a-z0-9]+(?:-[a-z0-9]+)*$/,
+    slugPatternMessage: "Use lowercase letters, numbers, and single dashes only.",
+    requiredTitleMessage: "Title is required.",
+    requiredSlugMessage: "Slug is required.",
+    requiredSummaryMessage: "Summary is required.",
+    requiredPromptMessage: "Prompt is required."
+  },
+  naming: {
+    course: "Course",
+    section: "Section",
+    module: "Module",
+    stage: "Stage",
+    question: "Question",
+    learner: "Learner",
+    reviewer: "Reviewer",
+    assignment: "Assignment"
+  }
+});
+```
+
+Notes:
+
+- Autosave notices are emitted through `notifications` callbacks passed to `HandbookLmsLearningWorkspace`.
+- If no external notification callbacks are provided, autosave notices are suppressed by default.
+- Manual save/submit notifications still work through the existing notification pathways.
+
+## Semver policy
+
+- `MAJOR`: Breaking API or schema contract changes.
+- `MINOR`: Backward-compatible API additions.
+- `PATCH`: Bug fixes and documentation-only updates.
+
+## Publishing
+
+This package is published to npm using the workflow at `.github/workflows/publish-handbook-lms.yml`.
+
+## Local development
+
+- Build compiled outputs: `npm run build --workspace @beanchain/handbook-lms`
+- Typecheck package only: `npm run typecheck --workspace @beanchain/handbook-lms`
+
+## Peer dependencies
+
+- `react`
+- `@mui/material`
+- `@mui/icons-material`
+- `@hello-pangea/dnd`
+- `@uiw/react-md-editor`
+- `zod`

package/dist/adapter/index.cjs

@@ -0,0 +1,4 @@
+'use strict';
+
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/adapter/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.cjs"}

package/dist/adapter/index.d.cts

@@ -0,0 +1 @@
+export { D as HandbookLmsAdapter } from '../index-caUTkZqX.cjs';

package/dist/adapter/index.d.ts

@@ -0,0 +1 @@
+export { D as HandbookLmsAdapter } from '../index-caUTkZqX.js';

package/dist/adapter/index.js

@@ -0,0 +1,3 @@
+import '../chunk-HOQRIQ33.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/adapter/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}