@intellectif/lk-react 1.0.0

package/dist/theme/ThemeProvider.d.ts

@@ -0,0 +1,39 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ThemeTokens } from '@intellectif/lk-core';
+import { ReactNode } from 'react';
+
+/**
+ * Dark-mode colour overrides, merged over {@link defaultTheme} by
+ * `ThemeProvider`. Colours only — spacing/typography/shape/motion are
+ * theme-invariant. All pairs verified WCAG 2.2 AA against the dark surface.
+ */
+declare const darkTheme: Partial<ThemeTokens>;
+
+/**
+ * Canonical default theme token values. `defaults.css` mirrors these exactly.
+ * Palette is a neutral monochrome (ElevenLabs-like) so the SDK is brand-neutral
+ * out of the box; consumers rebrand via `ThemeProvider`. All colour pairs are
+ * verified to meet WCAG 2.2 AA: 4.5:1 for normal text, 3:1 for UI / focus ring
+ * (see theme/__tests__/contrast.test.ts).
+ */
+declare const defaultTheme: ThemeTokens;
+
+interface ThemeProviderProps {
+    /** Partial token overrides. When provided, dark auto-detection is disabled. */
+    theme?: Partial<ThemeTokens>;
+    children: ReactNode;
+}
+/**
+ * Provides theme tokens to descendant activity components as scoped inline CSS
+ * custom properties on a wrapper `<div>`, and via {@link useTheme}.
+ *
+ * Resolution: an explicit `theme` prop merges over {@link defaultTheme} (and
+ * suppresses dark auto-detect, per Req 13.5). With no `theme` prop, the OS
+ * `prefers-color-scheme: dark` preference auto-applies {@link darkTheme}.
+ * SSR-safe: the server snapshot is always light, so hydration never mismatches.
+ */
+declare function ThemeProvider({ theme, children }: ThemeProviderProps): react_jsx_runtime.JSX.Element;
+/** Returns the currently active theme tokens (defaults when no provider). */
+declare function useTheme(): ThemeTokens;
+
+export { ThemeProvider, type ThemeProviderProps, darkTheme, defaultTheme, useTheme };

package/dist/theme/ThemeProvider.js

@@ -0,0 +1,3 @@
+export { ThemeProvider, darkTheme, defaultTheme, useTheme } from '../chunk-B3FUUKZ2.js';
+//# sourceMappingURL=ThemeProvider.js.map
+//# sourceMappingURL=ThemeProvider.js.map

package/dist/theme/ThemeProvider.js.map

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

package/dist/theme/defaults.css

@@ -0,0 +1,50 @@
+/*
+ * learning-kit default theme tokens.
+ *
+ * Tailwind-safety contract: this file contains ONLY :root custom-property
+ * declarations. No reset/normalize/preflight, no element selectors, no
+ * utility classes, no @layer/@apply. The --lk-* namespace is disjoint from
+ * Tailwind's --tw-* / --color-* / --spacing-*, so this is purely additive
+ * and cannot conflict with Tailwind preflight or consumer styles.
+ *
+ * Mirrors theme/tokens.ts (the canonical source). Keep in sync.
+ */
+:root {
+  /* Colours — neutral monochrome (mirrors tokens.ts) */
+  --lk-color-primary: #18181b;
+  --lk-color-primary-hover: #27272a;
+  --lk-color-surface: #ffffff;
+  --lk-color-surface-raised: #fafafa;
+  --lk-color-border: #e4e4e7;
+  --lk-color-text: #18181b;
+  --lk-color-text-muted: #52525b;
+  --lk-color-success: #15803d;
+  --lk-color-error: #b91c1c;
+  --lk-color-warning: #b45309;
+  --lk-color-focus-ring: #18181b;
+
+  /* Spacing */
+  --lk-spacing-xs: 4px;
+  --lk-spacing-sm: 8px;
+  --lk-spacing-md: 16px;
+  --lk-spacing-lg: 24px;
+  --lk-spacing-xl: 32px;
+
+  /* Typography */
+  --lk-font-family-base: system-ui, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  --lk-font-size-sm: 0.875rem;
+  --lk-font-size-base: 1rem;
+  --lk-font-size-lg: 1.125rem;
+  --lk-font-weight-normal: 400;
+  --lk-font-weight-bold: 700;
+  --lk-line-height-base: 1.5;
+
+  /* Shape */
+  --lk-radius-sm: 0.25rem;
+  --lk-radius-base: 0.5rem;
+  --lk-radius-lg: 0.75rem;
+
+  /* Motion */
+  --lk-transition-fast: 150ms ease;
+  --lk-transition-base: 250ms ease;
+}

package/dist/theme/skin.css

@@ -0,0 +1,352 @@
+/*
+ * learning-kit OPTIONAL default skin — a slick, neutral monochrome look
+ * (ElevenLabs-like). Entirely token-driven, so `ThemeProvider` / dark mode
+ * restyle it for free.
+ *
+ * Override contract: every rule lives in the `lk-skin` CSS cascade layer.
+ * Unlayered author styles ALWAYS win over layered styles, so a consumer can
+ * restyle any `.lk-*` hook with plain CSS and no `!important`. Import order:
+ *   import '@intellectif/lk-react/theme/defaults.css';  (tokens)
+ *   import '@intellectif/lk-react/theme/skin.css';      (this — optional)
+ * This file is NOT imported by the components; it is opt-in and is kept
+ * separate from the tokens-only `defaults.css` (Tailwind-safety contract).
+ */
+
+@layer lk-skin {
+  .lk-mc,
+  .lk-fib {
+    font-family: var(--lk-font-family-base);
+    font-size: var(--lk-font-size-base);
+    line-height: var(--lk-line-height-base);
+    color: var(--lk-color-text);
+    background: var(--lk-color-surface);
+    padding: var(--lk-spacing-lg);
+    border: 1px solid var(--lk-color-border);
+    border-radius: var(--lk-radius-lg);
+  }
+
+  .lk-mc *,
+  .lk-fib * {
+    box-sizing: border-box;
+  }
+
+  .lk-mc fieldset,
+  .lk-fib fieldset {
+    margin: 0;
+    padding: 0;
+    border: 0;
+  }
+
+  .lk-mc legend {
+    padding: 0;
+    margin-bottom: var(--lk-spacing-md);
+    font-size: var(--lk-font-size-lg);
+    font-weight: var(--lk-font-weight-bold);
+  }
+
+  /* ── Activity media (image / audio / video / embed) ──────────────────── */
+  .lk-media {
+    margin: 0 0 var(--lk-spacing-lg);
+  }
+
+  .lk-media-el {
+    display: block;
+    max-width: 100%;
+    height: auto;
+    border-radius: var(--lk-radius-base);
+    border: 1px solid var(--lk-color-border);
+  }
+
+  /* Responsive 16:9 frame for embedded players. */
+  .lk-media-embed {
+    position: relative;
+    width: 100%;
+    aspect-ratio: 16 / 9;
+  }
+
+  .lk-media-embed .lk-media-el {
+    position: absolute;
+    inset: 0;
+    width: 100%;
+    height: 100%;
+  }
+
+  /* ── Activity sequence (question-set pager) ──────────────────────────── */
+  .lk-seq-progress {
+    margin-bottom: var(--lk-spacing-sm);
+    font-size: var(--lk-font-size-sm);
+    font-weight: var(--lk-font-weight-bold);
+    color: var(--lk-color-text-muted);
+  }
+
+  .lk-seq-question:focus {
+    outline: none;
+  }
+
+  .lk-seq-nav {
+    display: flex;
+    justify-content: space-between;
+    gap: var(--lk-spacing-md);
+    margin-top: var(--lk-spacing-md);
+  }
+
+  .lk-seq-nav button {
+    padding: var(--lk-spacing-sm) var(--lk-spacing-lg);
+    font: inherit;
+    font-weight: var(--lk-font-weight-bold);
+    color: var(--lk-color-text);
+    background: var(--lk-color-surface);
+    border: 1px solid var(--lk-color-border);
+    border-radius: var(--lk-radius-base);
+    cursor: pointer;
+    transition: var(--lk-transition-fast);
+  }
+
+  .lk-seq-nav button:hover:not(:disabled) {
+    border-color: var(--lk-color-primary);
+  }
+
+  .lk-seq-nav button:disabled {
+    opacity: 0.5;
+    cursor: default;
+  }
+
+  /* ── Multiple choice options ─────────────────────────────────────────── */
+  .lk-mc-option {
+    display: flex;
+    align-items: center;
+    gap: var(--lk-spacing-sm);
+    padding: var(--lk-spacing-md);
+    margin-bottom: var(--lk-spacing-sm);
+    border: 1px solid var(--lk-color-border);
+    border-radius: var(--lk-radius-base);
+    background: var(--lk-color-surface);
+    cursor: pointer;
+    transition: var(--lk-transition-fast);
+  }
+
+  .lk-mc-option:hover {
+    border-color: var(--lk-color-primary);
+    background: var(--lk-color-surface-raised);
+  }
+
+  .lk-mc-option:has(input:checked) {
+    border-color: var(--lk-color-primary);
+    box-shadow: inset 0 0 0 1px var(--lk-color-primary);
+  }
+
+  .lk-mc-option:has(input:disabled) {
+    cursor: default;
+  }
+
+  .lk-mc-option[data-correct="true"] {
+    border-color: var(--lk-color-success);
+    box-shadow: inset 0 0 0 1px var(--lk-color-success);
+  }
+
+  .lk-mc-option[data-correct="false"]:has(input:checked) {
+    border-color: var(--lk-color-error);
+    box-shadow: inset 0 0 0 1px var(--lk-color-error);
+  }
+
+  .lk-mc-option input {
+    accent-color: var(--lk-color-primary);
+    width: 1rem;
+    height: 1rem;
+    margin: 0;
+  }
+
+  .lk-mc-option-feedback {
+    margin-left: auto;
+    font-size: var(--lk-font-size-sm);
+    color: var(--lk-color-text-muted);
+  }
+
+  /* ── Fill-in-the-blanks passage ──────────────────────────────────────── */
+  /* Generous line-height so inline blanks on wrapped lines never collide. */
+  .lk-fib-passage {
+    margin: 0 0 var(--lk-spacing-lg);
+    font-size: var(--lk-font-size-lg);
+    line-height: 2.6;
+  }
+
+  .lk-fib-blank {
+    position: relative;
+    display: inline-flex;
+    align-items: center;
+    gap: var(--lk-spacing-xs);
+    vertical-align: middle;
+    margin: 0 2px;
+  }
+
+  /* Explicit font metrics: `font: inherit` would pull the passage's large
+     line-height (2.6) into the field and balloon its height. */
+  .lk-fib-blank input {
+    font-family: var(--lk-font-family-base);
+    font-size: var(--lk-font-size-base);
+    line-height: 1.4;
+    color: var(--lk-color-text);
+    padding: 2px var(--lk-spacing-sm);
+    border: 1px solid var(--lk-color-border);
+    background: var(--lk-color-surface);
+    border-radius: var(--lk-radius-sm);
+    min-width: 7ch;
+    transition: var(--lk-transition-fast);
+  }
+
+  .lk-fib-blank input:hover {
+    border-color: var(--lk-color-primary);
+  }
+
+  /* Contained focus (no outline-offset) so the ring stays inside the line
+     box and never bleeds into the line above/below. */
+  .lk-fib-blank input:focus-visible {
+    outline: none;
+    border-color: var(--lk-color-focus-ring);
+    box-shadow: 0 0 0 2px var(--lk-color-focus-ring);
+  }
+
+  .lk-fib-blank input[data-correct="true"] {
+    border-color: var(--lk-color-success);
+  }
+
+  .lk-fib-blank input[data-correct="false"] {
+    border-color: var(--lk-color-error);
+  }
+
+  /* Icon hint button: a subtle circular affordance, not a text pill. */
+  .lk-fib-hint-btn {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    color: var(--lk-color-text-muted);
+    background: var(--lk-color-surface-raised);
+    border: 1px solid var(--lk-color-border);
+    border-radius: 50%;
+    padding: 3px;
+    line-height: 0;
+    cursor: pointer;
+  }
+
+  .lk-fib-hint-btn:hover {
+    border-color: var(--lk-color-primary);
+    color: var(--lk-color-text);
+  }
+
+  /* Inline per-blank feedback shown after submission. */
+  .lk-fib-blank-feedback {
+    margin-left: var(--lk-spacing-xs);
+    font-size: var(--lk-font-size-sm);
+    color: var(--lk-color-text-muted);
+  }
+
+  .lk-fib-blank-feedback[data-correct="true"] {
+    color: var(--lk-color-success);
+  }
+
+  .lk-fib-blank-feedback[data-correct="false"] {
+    color: var(--lk-color-error);
+  }
+
+  /* Learner control to declutter feedback after submission. */
+  .lk-fib-feedback-toggle {
+    margin-top: var(--lk-spacing-md);
+    font-size: var(--lk-font-size-sm);
+    color: var(--lk-color-text-muted);
+    background: none;
+    border: 0;
+    padding: 0;
+    cursor: pointer;
+    text-decoration: underline;
+  }
+
+  .lk-fib-feedback-toggle:hover {
+    color: var(--lk-color-text);
+  }
+
+  /* Revealed hint rendered as a floating popover above the blank. The empty
+     placeholder span (pre-reveal) is hidden so nothing shows until clicked. */
+  .lk-fib-blank [aria-live]:empty {
+    display: none;
+  }
+
+  .lk-fib-blank [aria-live]:not(:empty) {
+    position: absolute;
+    bottom: calc(100% + 6px);
+    left: 0;
+    z-index: 1;
+    max-width: 16rem;
+    padding: var(--lk-spacing-xs) var(--lk-spacing-sm);
+    font-size: var(--lk-font-size-sm);
+    line-height: var(--lk-line-height-base);
+    color: var(--lk-color-surface);
+    background: var(--lk-color-text);
+    border-radius: var(--lk-radius-sm);
+    box-shadow: 0 4px 12px rgb(0 0 0 / 18%);
+  }
+
+  /* Little caret pointing at the blank. */
+  .lk-fib-blank [aria-live]:not(:empty)::after {
+    content: "";
+    position: absolute;
+    top: 100%;
+    left: var(--lk-spacing-sm);
+    border: 5px solid transparent;
+    border-top-color: var(--lk-color-text);
+  }
+
+  .lk-fib-answer {
+    padding: var(--lk-spacing-xs) var(--lk-spacing-sm);
+    border-radius: var(--lk-radius-sm);
+    background: color-mix(in srgb, var(--lk-color-success) 14%, var(--lk-color-surface));
+    color: var(--lk-color-text);
+    font-weight: var(--lk-font-weight-bold);
+  }
+
+  /* ── Submit buttons ──────────────────────────────────────────────────── */
+  .lk-mc button[type="submit"],
+  .lk-fib button[type="submit"] {
+    margin-top: var(--lk-spacing-md);
+    padding: var(--lk-spacing-sm) var(--lk-spacing-lg);
+    font: inherit;
+    font-weight: var(--lk-font-weight-bold);
+    color: var(--lk-color-surface);
+    background: var(--lk-color-primary);
+    border: 0;
+    border-radius: var(--lk-radius-base);
+    cursor: pointer;
+    transition: var(--lk-transition-fast);
+  }
+
+  .lk-mc button[type="submit"]:hover,
+  .lk-fib button[type="submit"]:hover {
+    background: var(--lk-color-primary-hover);
+  }
+
+  .lk-mc button[type="submit"]:disabled,
+  .lk-fib button[type="submit"]:disabled {
+    opacity: 0.55;
+    cursor: default;
+  }
+
+  /* ── Focus ring (keyboard) ───────────────────────────────────────────── */
+  .lk-mc :focus-visible,
+  .lk-fib :focus-visible {
+    outline: 2px solid var(--lk-color-focus-ring);
+    outline-offset: 2px;
+  }
+
+  /* Inline controls in the passage use a contained ring (no offset) so the
+     focus indicator never overlaps the line above/below. */
+  .lk-fib-blank button:focus-visible {
+    outline-offset: 0;
+  }
+
+  /* ── Feedback / status region ────────────────────────────────────────── */
+  .lk-mc > [aria-live],
+  .lk-fib > [aria-live] {
+    margin-top: var(--lk-spacing-md);
+    color: var(--lk-color-text-muted);
+    font-size: var(--lk-font-size-sm);
+  }
+}

package/dist/types-iknDq5tf.d.cts

@@ -0,0 +1,17 @@
+import { ActivityData, ActivityResult, InteractionEvent, ThemeTokens } from '@intellectif/lk-core';
+
+/**
+ * The consistent prop contract shared by every activity component (Req 3.1).
+ * Defined here (React-specific) rather than in lk-core, which is React-free.
+ */
+interface ActivityProps<TData extends ActivityData = ActivityData> {
+    data: TData;
+    onComplete: (result: ActivityResult) => void;
+    onInteraction?: (event: InteractionEvent) => void;
+    /** Per-instance token overrides, applied as inline CSS vars on the root. */
+    theme?: Partial<ThemeTokens>;
+    locale?: string;
+    disabled?: boolean;
+}
+
+export type { ActivityProps as A };

package/dist/types-iknDq5tf.d.ts

@@ -0,0 +1,17 @@
+import { ActivityData, ActivityResult, InteractionEvent, ThemeTokens } from '@intellectif/lk-core';
+
+/**
+ * The consistent prop contract shared by every activity component (Req 3.1).
+ * Defined here (React-specific) rather than in lk-core, which is React-free.
+ */
+interface ActivityProps<TData extends ActivityData = ActivityData> {
+    data: TData;
+    onComplete: (result: ActivityResult) => void;
+    onInteraction?: (event: InteractionEvent) => void;
+    /** Per-instance token overrides, applied as inline CSS vars on the root. */
+    theme?: Partial<ThemeTokens>;
+    locale?: string;
+    disabled?: boolean;
+}
+
+export type { ActivityProps as A };

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@intellectif/lk-react",
+  "version": "1.0.0",
+  "description": "React 19 activity components, hooks, and theming for learning-kit",
+  "type": "module",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./components/ActivitySequence": {
+      "types": "./dist/components/ActivitySequence.d.ts",
+      "import": "./dist/components/ActivitySequence.js",
+      "require": "./dist/components/ActivitySequence.cjs"
+    },
+    "./components/MultipleChoice": {
+      "types": "./dist/components/MultipleChoice.d.ts",
+      "import": "./dist/components/MultipleChoice.js",
+      "require": "./dist/components/MultipleChoice.cjs"
+    },
+    "./components/FillInTheBlanks": {
+      "types": "./dist/components/FillInTheBlanks.d.ts",
+      "import": "./dist/components/FillInTheBlanks.js",
+      "require": "./dist/components/FillInTheBlanks.cjs"
+    },
+    "./hooks/useActivityState": {
+      "types": "./dist/hooks/useActivityState.d.ts",
+      "import": "./dist/hooks/useActivityState.js",
+      "require": "./dist/hooks/useActivityState.cjs"
+    },
+    "./hooks/useXAPI": {
+      "types": "./dist/hooks/useXAPI.d.ts",
+      "import": "./dist/hooks/useXAPI.js",
+      "require": "./dist/hooks/useXAPI.cjs"
+    },
+    "./theme/ThemeProvider": {
+      "types": "./dist/theme/ThemeProvider.d.ts",
+      "import": "./dist/theme/ThemeProvider.js",
+      "require": "./dist/theme/ThemeProvider.cjs"
+    },
+    "./theme/defaults.css": "./dist/theme/defaults.css",
+    "./theme/skin.css": "./dist/theme/skin.css"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "react": "^19",
+    "react-dom": "^19",
+    "@intellectif/lk-core": "^0.2.0"
+  },
+  "devDependencies": {
+    "@axe-core/react": "^4.10.0",
+    "@playwright/test": "^1.49.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.1.0",
+    "@testing-library/user-event": "^14.5.2",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitest/coverage-v8": "^4.1.6",
+    "fast-check": "^3.22.0",
+    "jsdom": "^25.0.1",
+    "msw": "^2.6.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.3.0",
+    "vitest": "^4.1.6",
+    "vitest-axe": "^0.1.0",
+    "@intellectif/lk-core": "0.2.0"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "coverage": "vitest run --coverage",
+    "lint": "biome check .",
+    "e2e": "playwright test -c ../../playwright.config.ts"
+  }
+}