@intellectif/lk-react 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +112 -0
  2. package/package.json +8 -3
package/README.md ADDED
@@ -0,0 +1,112 @@
1
+ # @intellectif/lk-react
2
+
3
+ React 19 components, hooks, and theming for [learning-kit](https://github.com/intellectif/learning-kit): accessible interactive activity components (Multiple Choice, Fill-in-the-Blanks), an in-place question-set pager, a CSS-variable theming system with an optional skin, and an xAPI delivery hook.
4
+
5
+ A lightweight, composable, bring-your-own-backend alternative to H5P.
6
+
7
+ ```bash
8
+ pnpm add @intellectif/lk-react @intellectif/lk-core react react-dom
9
+ # or
10
+ npm install @intellectif/lk-react @intellectif/lk-core react react-dom
11
+ ```
12
+
13
+ > `@intellectif/lk-core`, `react`, and `react-dom` are peer dependencies (React `^19`).
14
+
15
+ ## Quick start
16
+
17
+ ```tsx
18
+ import type { MultipleChoiceData } from '@intellectif/lk-core';
19
+ import { MultipleChoice } from '@intellectif/lk-react/components/MultipleChoice';
20
+ import { ThemeProvider } from '@intellectif/lk-react/theme/ThemeProvider';
21
+ import { useXAPI } from '@intellectif/lk-react/hooks/useXAPI';
22
+ import '@intellectif/lk-react/theme/defaults.css'; // design tokens (required)
23
+ import '@intellectif/lk-react/theme/skin.css'; // optional polished skin
24
+
25
+ const quiz: MultipleChoiceData = {
26
+ schemaVersion: '1.0',
27
+ type: 'multiple-choice',
28
+ id: 'capital-jp',
29
+ title: 'World Capitals',
30
+ question: 'Which city is the capital of Japan?',
31
+ mode: 'single',
32
+ scoringStrategy: 'all-or-nothing',
33
+ options: [
34
+ { id: 'tokyo', text: 'Tokyo', isCorrect: true, feedback: 'Correct!' },
35
+ { id: 'seoul', text: 'Seoul', isCorrect: false, feedback: "That's South Korea." },
36
+ ],
37
+ feedback: { correct: 'Nicely done!', incorrect: 'Review and try again.' },
38
+ };
39
+
40
+ export function Demo() {
41
+ const { sendStatement } = useXAPI({
42
+ endpoint: 'https://your-lrs.example/xapi/statements',
43
+ auth: { type: 'bearer', token: 'YOUR_TOKEN' },
44
+ activityId: 'https://your-app.example/quiz/capital-jp',
45
+ actor: { objectType: 'Agent', mbox: 'mailto:learner@example.com' },
46
+ onError: (e) => console.error('xAPI send failed', e),
47
+ });
48
+
49
+ return (
50
+ <ThemeProvider>
51
+ <MultipleChoice
52
+ data={quiz}
53
+ onComplete={(result) => {
54
+ // result: { score, maxScore, passed, timeSpent, xapiStatement }
55
+ void sendStatement(result.xapiStatement); // never throws
56
+ }}
57
+ />
58
+ </ThemeProvider>
59
+ );
60
+ }
61
+ ```
62
+
63
+ ## Activities & features
64
+
65
+ - **`<MultipleChoice>`** — single / multi select, all-or-nothing or partial scoring, deterministic per-session shuffle, per-option `feedback`.
66
+ - **`<FillInTheBlanks>`** — `{{id}}` placeholders, case/whitespace options, per-blank `hint` (Show/Hide toggle as an icon), per-blank `feedback` shown inline on submit with a learner-controlled **Hide/Show feedback** toggle, optional `showCorrectAnswers`.
67
+ - **`<ActivitySequence>`** — in-place "question set" pager (Previous/Next, "Question X of N", no scrolling, focus-managed).
68
+ - **Media per question** — optional `image` / `audio` / `video` / `embed` (YouTube/Vimeo iframe) above the question; alt-text required for `image`/`embed` (WCAG).
69
+ - **Activity-level overall feedback** — `{ correct, incorrect }` shown after submit (h5p "Overall Feedback" parity).
70
+ - **`useXAPI(config)`** — fire-and-forget LRS delivery with retry/backoff for 5xx/network (1 s / 2 s / 4 s), immediate fail on 4xx, never throws.
71
+ - **`useActivityState()`** — `idle → in-progress → completed → reviewing` machine with `getTimeSpent()`.
72
+ - **`<ThemeProvider>` + `defaults.css`** — `--lk-*` design-token system; automatic dark mode via `prefers-color-scheme` (SSR-safe with `useSyncExternalStore`).
73
+ - **`createTailwindTheme(theme)`** — optional Tailwind interop; consume the SDK palette from your own utilities.
74
+ - **WCAG 2.2 AA** — axe-clean unit + Playwright e2e tests; full keyboard operability; numerically-verified contrast.
75
+ - **RSC-compatible** — every component carries `'use client'` and hydrates inside a React Server Component tree.
76
+
77
+ ## Subpath exports
78
+
79
+ | Import | Contents |
80
+ |---|---|
81
+ | `@intellectif/lk-react` | Everything (barrel) |
82
+ | `@intellectif/lk-react/components/MultipleChoice` | `<MultipleChoice>` (boundary-wrapped) |
83
+ | `@intellectif/lk-react/components/FillInTheBlanks` | `<FillInTheBlanks>` (boundary-wrapped) |
84
+ | `@intellectif/lk-react/components/ActivitySequence` | `<ActivitySequence>` question-set pager |
85
+ | `@intellectif/lk-react/hooks/useActivityState` | Lifecycle + timing |
86
+ | `@intellectif/lk-react/hooks/useXAPI` | LRS delivery (retry, never-throws) |
87
+ | `@intellectif/lk-react/theme/ThemeProvider` | `<ThemeProvider>`, `darkTheme`, `useTheme`, `createTailwindTheme` |
88
+ | `@intellectif/lk-react/theme/defaults.css` | Tokens (required) |
89
+ | `@intellectif/lk-react/theme/skin.css` | Optional polished skin |
90
+
91
+ ESM + CJS + `.d.ts` for every entry. Tree-shakeable.
92
+
93
+ ## Capabilities & limitations (V1)
94
+
95
+ | Concern | Behavior |
96
+ |---|---|
97
+ | **Scoring** | Pure & deterministic; `all-or-nothing` and `partial`. |
98
+ | **Feedback** | Per-item (MC per-option, FIB per-blank) shown inline on submit with Hide/Show toggle, + activity-level overall. |
99
+ | **Retry** | Pass a new `data` reference or change the React `key` → activity resets (no built-in button — retry *policy* is yours). |
100
+ | **Persistence / resume** | Not in the SDK — capture `onInteraction` / `onComplete` and persist as you wish. No `initialResponse` prop in V1 (cannot re-hydrate a partial attempt). |
101
+ | **Authoring / content storage / CDN / auth** | Consumer responsibility — typed schemas + `validateActivity` + JSON Schema export are provided for you to build authoring on. |
102
+ | **SSR / RSC** | Fully supported. |
103
+
104
+ ## Documentation
105
+
106
+ - [Authoring & content storage](https://github.com/intellectif/learning-kit/blob/main/docs/authoring.md)
107
+ - [Styling](https://github.com/intellectif/learning-kit/blob/main/docs/styling.md) — tokens, the skin, overrides, dark mode, Tailwind.
108
+ - [Project README](https://github.com/intellectif/learning-kit#readme) — full picture & monorepo layout.
109
+
110
+ ## License
111
+
112
+ MIT © [Intellectif LLC](https://intellectif.com)
package/package.json CHANGED
@@ -1,7 +1,12 @@
1
1
  {
2
2
  "name": "@intellectif/lk-react",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "React 19 activity components, hooks, and theming for learning-kit",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "https://github.com/intellectif/learning-kit.git",
8
+ "directory": "packages/lk-react"
9
+ },
5
10
  "type": "module",
6
11
  "sideEffects": [
7
12
  "**/*.css"
@@ -54,7 +59,7 @@
54
59
  "peerDependencies": {
55
60
  "react": "^19",
56
61
  "react-dom": "^19",
57
- "@intellectif/lk-core": "^0.2.0"
62
+ "@intellectif/lk-core": "^0.2.1"
58
63
  },
59
64
  "devDependencies": {
60
65
  "@axe-core/react": "^4.10.0",
@@ -73,7 +78,7 @@
73
78
  "tsup": "^8.3.0",
74
79
  "vitest": "^4.1.6",
75
80
  "vitest-axe": "^0.1.0",
76
- "@intellectif/lk-core": "0.2.0"
81
+ "@intellectif/lk-core": "0.2.1"
77
82
  },
78
83
  "license": "MIT",
79
84
  "scripts": {