cognikit 0.2.0 → 1.0.0

package/README.md

@@ -1,316 +1,388 @@
-# COGNIKIT
+# Cognikit
 
-A TypesScript framework for creating cognitively-grounded assessment systems, quizzes and interactive educationally-oriented exercises. 
-It is built on research in assessment design, psycometrics and cognitive science, while not limiting itself from implementing from casual 
-environments like classrooms (the author, *me*, is a teacher), and being flexible enough to be used in other contexts like games, articles, 
-and more.
+Cognikit is a browser-first toolkit for building cognitive and educational interactions: classification, recall, recognition, text activities, and table-based tasks.
 
----
+It gives you two main integration styles:
 
-## Overview
+- `shell + interaction`: use the built-in shell for prompt display, timer, progress, retry, score, and navigation.
+- `shell-less interaction`: mount an interaction directly and manage the surrounding UI yourself.
 
-'Cognikit' provides a structured approach to building educational assessments while aligning them with specific cognitive processes, a curated list
-of the later which are suitable for simple implementations anywhere and do not require "heavy machinery" to do so.
+## What It Includes
 
-Key end-use features:
+- Built-in interaction classes such as `OpenClassification`, `SequentialClassification`, `MCQ`, `ListRecall`, `RankOrder`, text interactions, and table interactions.
+- `createInteraction(id, data, config, assets)` for runtime creation from a registry id.
+- `InteractionsBaseShell` for a ready-made interaction container.
+- Asset parsing and validation helpers.
+- Theme and audio configuration helpers.
+- SSR compatibility guards for browser-oriented environments.
 
-- **Simple authoring for each interaction**
-- **Validators to enforce constraints over the data passed to the interactions**
-- **Utility Components**
-- **Engines for unique tools**
-- **Styling variations supporting components**
-- **Grading utilities**
+## Install
 
-Key development features:
+```bash
+pnpm add cognikit
+```
 
-- **One dependency**
-- **Uses vanilla web technologies (and typescript)**
-- **Strongly typed system**
-- **Modular Arquitecture**
-- **Mixes up OOP and FP**
+## Basic Setup
 
----
+The package is browser-oriented. In frameworks like React or Next.js, create and mount interactions inside a client-side effect.
 
-Take a look at the file structure to also visualize some of the features mentioned:
+```ts
+import * as cognikit from "cognikit";
 
-```txt
-src/
-	// base *abstract* class which is used for all other interactions.
-	// It itself depends on the *shell* custom component at @shell
-	core/
-		BaseInteraction.ts
-	
-	// modules which on themselves provide the *interactions*, more detailed later
-	modules/
-		classification/
-		discrimination/
-		recognition/
-		seriation/
-		comparison/
-		...
-
-	engines/
-		tables/
-		html/
-		...
-	
-	// Custom base component that listens to the events of an interactions and triggers features like
-	// progress, radio navigation, check button, prompt visualization and timer.
-	shell/
-	    base/
-            script.ts
-
-	ui/
-		input/
-		misc/
-
-	shared/
-		...
-
-	types/
-		Tables.ts
-		Grading.ts
+cognikit.configureCognikit({
+  audioBaseUrl: "/assets/audio/",
+  theme: "default-light",
+});
 ```
 
-Each 'module' follow a designed pattern:
+## Quick Start: Shell + Interaction
+
+This is the recommended path if you want the packaged UX.
 
+```ts
+import * as cognikit from "cognikit";
+
+const shell = new cognikit.InteractionsBaseShell();
+
+const data = {
+  type: "sequential-classification",
+  categories: [
+    { label: "Ocean", items: ["Dolphin", "Shark", "Octopus"] },
+    { label: "Land", items: ["Lion", "Elephant", "Tiger"] },
+    { label: "Air", items: ["Eagle", "Parrot", "Hawk"] },
+  ],
+};
+
+const config = {
+  prompt: "Sort the animals by habitat",
+  variant: "elegant",
+  shuffle: true,
+  attemptLimit: 2,
+  timer: 120,
+  animationsEnabled: true,
+  soundEnabled: true,
+};
+
+const interaction = cognikit.createInteraction(
+  "sequential-classification",
+  data,
+  config,
+  null,
+);
+
+shell.setInteraction(interaction);
+document.body.appendChild(shell);
 ```
-modules/<process>/
-	module.ts			// Central object that exports all features of the module
-	interactions/
-		<interaction>.ts	// Classes that extend the *BaseInteraction* abstract class to create a unique way to complete an item
-    utilitits/
-        parser.ts
-        grader.ts
-        validator.ts
-	doc/
-		interactions.ts  	// Use the "IInteraction" interface and works as a programmatic documentation object
-		<process>.md		// Research and justification of the 'conginitive process' 
+
+![Interaction Example](public/assets/DEMONSTRATION-1.jpeg)
+
+### What the shell gives you
+
+- Prompt header
+- Timer
+- Progress bar
+- Check / retry controls
+- Score screen
+- Sequential navigation for interactions that expose steps
+- Basic error screen for invalid interactions
+
+## Shell-less Interactions
+
+If you want full control over layout and surrounding controls, mount the interaction directly.
+
+```ts
+import { ListRecall } from "cognikit";
+
+const interaction = new ListRecall(
+  {
+    type: "seriation",
+    items: ["Passport", "Wallet", "Keys", "Phone"],
+  },
+  {
+    prompt: "Recall the travel checklist",
+    variant: "minimal",
+    shuffle: false,
+    attemptLimit: 1,
+    timer: null,
+    animationsEnabled: true,
+    soundEnabled: true,
+  },
+);
+
+document.querySelector("#app")?.appendChild(interaction);
 ```
 
----
+Use shell-less mode when:
+
+- you already have your own timer / scoring UI
+- you want to embed interactions into an existing app layout
+- you want tighter control over fullscreen, dialogs, or analytics
 
-### Architecture Overview
+## Assets
 
-[https://sage-babka-680d4e.netlify.app]
+Some interactions and prompts can reference assets such as images, video, audio, HTML, or TTS.
 
-### Common Patterns
+### YAML assets
 
-There are built-in parsers that read a specific pattern in a string and generate the data for the interaction, but the data
-can be generated in any other way and ultimatilely GUI forms are best for managing assets.
+```yaml
+butterfly:
+  type: image
+  url: https://example.com/butterfly.jpg
 
-Check this example workflow (doesn't utilize assets):
+intro_audio:
+  type: audio
+  url: https://example.com/intro.mp3
+  volume: 80
+```
+
+### Parse and validate
 
 ```ts
-// *CLASSIFICATION* module 'DSL'
-const data = `
-AMERICA = DR 	     | USA | Mexico;
-ASIA    = Thailand   | PNG | India | Mongolia;
-Africa  = Madagascar | Kenya;
-= Antartica | Greenland;
+import { parseYamlAssets, validateAndNormalizeAssets } from "cognikit";
+
+const yaml = `
+butterfly:
+  type: image
+  url: https://example.com/butterfly.jpg
 `;
 
-const parsedData = classificationParser(data);
-const isValid = classificationValidator(parsedData);
-
-if (isValid) {
-	console.log(parsedData);
-}
-
-/** Which would be equal to something like this:
- * [
- * 	{ label: 'AMERICA', items: [ 'DR', 'USA', 'Mexico ] },
- *	{ label: 'ASIA', items: [ 'Thailand', 'PNG', 'India', 'Mongolia' ] },
- *  	{ label: 'Africa', items: [ 'Madagascar' | 'Kenya' ] }
- * ],
- * [ 'Antartica', 'Greenland' ] -> These are distractors
- */ 
+const assets = validateAndNormalizeAssets(parseYamlAssets(yaml));
 ```
 
-Example expected data objects
+If validation fails, Cognikit throws `AssetValidationError`.
+
+To be able to use these assets in an interaction, you need to set <@:assetName> in the data value.
+
 ```ts
-interface ClassificationData {
-	type: 'classification'; 
-	categories: { label: string; items: string[] }[];
-	distractors?: string[];
-}
-
-interface AssociationData {
-	type: 'association';
-	pairs: { left: string; right: string }[];
-	distractors?: string[];
-}
-
-interface FreeRecallData {
-	type: 'freerecall';
-	instructions: { prompt: string; words: string[] }[];
-}
+const assets = ...;
+
+// supposing you have a asset name called "phone"
+const data = {
+    type: "seriation",
+    items: ["Passport", "Wallet", "Keys", "@:phone"],
+};
 ```
 
-## NOTES
+## Configuring Theme
 
-1) Each module has a unique text-based way of representing their required data
-2) Each data model is defined in the central types (@src/shared/types.ts)
-3) While it's heavily focused on this method, the way to construct the data can be done in any other way, interactions are unrelated to those processes
-4) ** The 'engines' use this pattern too, but the way to use them is different since they are stand-alone.**
+Cognikit exposes preset themes and theme variable overrides.
 
 ```ts
-// example "interaction" that uses the *TABLES* engine
-export class ClassificationMatrix extends BaseInteraction<BaseTableData> {
+import { configureCognikit } from "cognikit";
 
-    private _tableConfig: TableConfiguration;
-    private _$table!: EduTable;
+configureCognikit({
+  theme: "default-dark",
+});
+```
 
-    constructor(options: InteractionOptions<BaseTableData>) {
-        super(options);
+Available built-in themes:
 
-        this._tableConfig = {
-            rows: this.data.rows,
-            cols: this.data.cols,
-            answerKey: this.data.answerKey,
-            cellKind: 'checkbox',
-            preset: 'classification',
-            variant: this.data.variant ?? 'outline'
-        };
+- `default-light`
+- `default-dark`
+- `ocean-light`
+- `ocean-dark`
+- `forest-light`
+- `forest-dark`
 
-        this.initializeProgress(this.data.rows.length);
-    }
+### Custom theme variables
 
-    render(): void {
-        const content = this.getContentArea();
+```ts
+configureCognikit({
+  theme: "default-light",
+  themeVariables: {
+    "--edu-first-accent": "124 58 237",
+    "--edu-radius": "0.75rem",
+    "--edu-card": "255 255 255",
+  },
+});
+```
 
-        this._$table = document.createElement('edu-table') as EduTable;
-        this._$table.config = this._tableConfig;
+### Theme helpers
 
-        content.innerHTML = '';
-        content.append(this._$table);
-    }
+You can also use:
 
-    getCurrentState(): any {
-        return this._$table.getState();
-    }
+- `ensureCognikitTheme()`
+- `getCognikitConfig()`
+- `getCognikitThemePresets()`
+- `resolveCognikitTheme()`
+- `setCognikitTheme()`
+- `resetCognikitTheme()`
+- `defaultCognikitThemeVariables`
+- `cognikitThemePresets`
 
-    isInteractionComplete(): boolean {
-        return false;
-    }
-}
-```
+## Configuring Audio
 
----
+Built-in shell and interaction sounds resolve through Cognikit config.
 
-## Variant System
+```ts
+configureCognikit({
+  audioBaseUrl: "/assets/audio/",
+});
+```
 
-All custom components support a `variant` attribute for consistent theming:
+You can also override named sound files:
 
 ```ts
-type Variant =
-    | 'elegant'   
-    | 'playful'  
-    | 'outline' 
-    | 'letter' 
-    | 'sign'   
-    | 'minimal'
-    | 'glass' 
-    | 'empty';
+configureCognikit({
+  audioBaseUrl: "/assets/audio/",
+  soundFiles: {
+    start: "custom-start.mp3",
+    success: "custom-success.mp3",
+    failure: "custom-failure.mp3",
+  },
+});
 ```
 
-Variants are applied via CSS host selectors:
+## Interaction Setup
 
-```css
-:host([variant="elegant"]) {
-    /* Elegant styling */
-}
+Most interactions use the same setup pattern:
 
-:host([variant="playful"]) {
-    /* Playful styling */
-}
-```
+1. Prepare `data`
+2. Prepare `config`
+3. Optionally parse and validate `assets`
+4. Create the interaction
+5. Mount it directly or pass it into `InteractionsBaseShell`
 
----
+### Data types
 
-### SPECIFICS
+Cognikit currently exposes these base data shapes:
 
-Most subdirectories that introduce some sort of system or important file provide a README.md that is to be read to get more insight on what it does and
-how it works. This overview here provides a great general idea of how everything pretty much works, but reading specifics is also necessary.
+- `ClassificationData`
+- `AssociationData`
+- `RecognitionData`
+- `SeriationData`
+- `FreeRecallData`
+- table data types
+- text engine data types
 
----
+### Example configs
 
-## Development
+```ts
+const config = {
+  prompt: "Arrange the butterfly life cycle",
+  variant: "outline",
+  shuffle: true,
+  attemptLimit: 2,
+  timer: 180,
+  animationsEnabled: true,
+  soundEnabled: true,
+};
+```
 
-### Setup
+Important config fields:
+
+- `prompt`
+- `variant`
+- `shuffle`
+- `attemptLimit`
+- `timer`
+- `animationsEnabled`
+- `soundEnabled`
+- `promptModality`
+- `promptData`
+- `promptDataSpec`
+
+## Built-in Interaction Registry IDs
+
+These ids are registered out of the box and work with `createInteraction(...)`:
+
+- `open-classification`
+- `sequential-classification`
+- `mcq`
+- `simultaneous-association`
+- `list-recall`
+- `lookup-table`
+- `classification-matrix`
+- `nary-choice-table`
+- `adjacency-table`
+- `mark-the-words`
+- `sequential-mark-the-words`
+- `categorize-the-words`
+- `sequential-categorize-the-words`
+- `text-transformation`
+- `sequential-text-transformation`
+- `fill-blanks`
+- `sequential-fill-blanks`
+- `rank-order`
+
+## Recommended Imports
+
+### General use
 
-```bash
-pnpm install
+```ts
+import * as cognikit from "cognikit";
 ```
 
-### Scripts
+### Named imports
 
-```bash
-pnpm dev           # Watch mode with hot reload
-pnpm build         # Build library + types + demo
-pnpm build:lib     # Build library only
-pnpm build:demo    # Build demo app
-pnpm types
-pnpm serve
-pnpm clean
+```ts
+import {
+  createInteraction,
+  InteractionsBaseShell,
+  configureCognikit,
+  parseYamlAssets,
+  validateAndNormalizeAssets,
+} from "cognikit";
 ```
 
-### Build Configuration
+### Client-focused entry
 
-- **Bundler**: esbuild
-- **Module Format**: ESM
-- **Platform**: Browser
-- **Loaders**:
-  - `.html` files as text
-  - `.css` files as text
+```ts
+import * as cognikit from "cognikit/client";
+```
 
----
+The `client` entrypoint ensures built-ins are registered and theme variables are applied immediately in client-only usage.
 
-## Usage
+## React / Next.js Notes
 
-### Creating a Module
+- Use Cognikit inside a client component.
+- Mount shells and interactions inside `useEffect`.
+- If you switch between dark and light site themes, call `configureCognikit({ theme: ... })` when the app theme changes.
+- If you want fullscreen previews, it is usually cleaner to create a second shell instance for the overlay rather than moving the same DOM node around.
 
-1. Create directory: `src/modules/<process>/`
-2. Implement parser, validator, grader in `utilities/`
-3. Create interaction classes in `interactions/`
-4. Define module metadata in `module.ts`
-5. Document in `doc/`
+## Project Structure
 
-### Creating an Interaction
+High-level layout:
+
+```text
+src/
+  core/           Base interaction primitives
+  interactions/   Built-in interaction classes and registry
+  engines/        Text and table engines
+  shell/          Shell UI
+  shared/         Config, assets, utils, managers
+  types/          Public types
+  ui/             Reusable custom elements
+public/
+  index.html
+  app.js
+  demo assets
+```
 
-```typescript
-import { BaseInteraction } from 'core';
-import { InteractionOptions } from "types/interactions";
-import { NormalizedAssets } from "shared/assets";
-import { MyInteractionData } from "...";
+Key files:
 
-export class MyInteraction extends BaseInteraction<MyDataType> {
+- `src/index.ts`: primary package entrypoint
+- `src/client.ts`: client-focused entrypoint
+- `src/interactions/register-builtins.ts`: built-in registry ids
+- `src/shared/config.ts`: theme and audio configuration
+- `src/shared/assets.ts`: asset validation
 
-    constructor(data: MyInteractionData, config: InteractionConfig, assets?: NormalizedAssets) {
-        super(data, config, assets);
-        this.initializeProgress(/* total steps */);
-    }
+## Local Development
 
-    render(): void {
-        const content = this.getContentArea();
-        // Render interaction UI
-    }
+```bash
+pnpm install
+pnpm dev
+```
 
-    getCurrentState(): any {
-        // Return current user state
-    }
+Useful scripts:
 
-    isInteractionComplete(): boolean {
-        // Check completion status
-    }
+- `pnpm build`
+- `pnpm build:lib`
+- `pnpm build:demo`
+- `pnpm types`
+- `pnpm serve`
 
-    protected submitForScoring(): void {
-        const state = this.getCurrentState();
-        // Grade and handle result
-    }
-}
-```
+## License
 
-## Contributing
+MIT
 
-This is a research project in active development. Feedback and contributions welcome at the GitHub repository.