cognikit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yahir Adolfo de los Santos Beras
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,316 @@
+# 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.
+
+---
+
+## Overview
+
+'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.
+
+Key end-use features:
+
+- **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**
+
+Key development features:
+
+- **One dependency**
+- **Uses vanilla web technologies (and typescript)**
+- **Strongly typed system**
+- **Modular Arquitecture**
+- **Mixes up OOP and FP**
+
+---
+
+Take a look at the file structure to also visualize some of the features mentioned:
+
+```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
+```
+
+Each 'module' follow a designed pattern:
+
+```
+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' 
+```
+
+---
+
+### Architecture Overview
+
+[https://sage-babka-680d4e.netlify.app]
+
+### Common Patterns
+
+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.
+
+Check this example workflow (doesn't utilize assets):
+
+```ts
+// *CLASSIFICATION* module 'DSL'
+const data = `
+AMERICA = DR 	     | USA | Mexico;
+ASIA    = Thailand   | PNG | India | Mongolia;
+Africa  = Madagascar | Kenya;
+= Antartica | Greenland;
+`;
+
+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
+ */ 
+```
+
+Example expected data objects
+```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[] }[];
+}
+```
+
+## NOTES
+
+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.**
+
+```ts
+// example "interaction" that uses the *TABLES* engine
+export class ClassificationMatrix extends BaseInteraction<BaseTableData> {
+
+    private _tableConfig: TableConfiguration;
+    private _$table!: EduTable;
+
+    constructor(options: InteractionOptions<BaseTableData>) {
+        super(options);
+
+        this._tableConfig = {
+            rows: this.data.rows,
+            cols: this.data.cols,
+            answerKey: this.data.answerKey,
+            cellKind: 'checkbox',
+            preset: 'classification',
+            variant: this.data.variant ?? 'outline'
+        };
+
+        this.initializeProgress(this.data.rows.length);
+    }
+
+    render(): void {
+        const content = this.getContentArea();
+
+        this._$table = document.createElement('edu-table') as EduTable;
+        this._$table.config = this._tableConfig;
+
+        content.innerHTML = '';
+        content.append(this._$table);
+    }
+
+    getCurrentState(): any {
+        return this._$table.getState();
+    }
+
+    isInteractionComplete(): boolean {
+        return false;
+    }
+}
+```
+
+---
+
+## Variant System
+
+All custom components support a `variant` attribute for consistent theming:
+
+```ts
+type Variant =
+    | 'elegant'   
+    | 'playful'  
+    | 'outline' 
+    | 'letter' 
+    | 'sign'   
+    | 'minimal'
+    | 'glass' 
+    | 'empty';
+```
+
+Variants are applied via CSS host selectors:
+
+```css
+:host([variant="elegant"]) {
+    /* Elegant styling */
+}
+
+:host([variant="playful"]) {
+    /* Playful styling */
+}
+```
+
+---
+
+### SPECIFICS
+
+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.
+
+---
+
+## Development
+
+### Setup
+
+```bash
+pnpm install
+```
+
+### Scripts
+
+```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
+```
+
+### Build Configuration
+
+- **Bundler**: esbuild
+- **Module Format**: ESM
+- **Platform**: Browser
+- **Loaders**:
+  - `.html` files as text
+  - `.css` files as text
+
+---
+
+## Usage
+
+### Creating a Module
+
+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/`
+
+### Creating an Interaction
+
+```typescript
+import { BaseInteraction } from 'core';
+import { InteractionOptions } from "types/interactions";
+import { NormalizedAssets } from "shared/assets";
+import { MyInteractionData } from "...";
+
+export class MyInteraction extends BaseInteraction<MyDataType> {
+
+    constructor(data: MyInteractionData, config: InteractionConfig, assets?: NormalizedAssets) {
+        super(data, config, assets);
+        this.initializeProgress(/* total steps */);
+    }
+
+    render(): void {
+        const content = this.getContentArea();
+        // Render interaction UI
+    }
+
+    getCurrentState(): any {
+        // Return current user state
+    }
+
+    isInteractionComplete(): boolean {
+        // Check completion status
+    }
+
+    protected submitForScoring(): void {
+        const state = this.getCurrentState();
+        // Grade and handle result
+    }
+}
+```
+
+## Contributing
+
+This is a research project in active development. Feedback and contributions welcome at the GitHub repository.

package/dist/core/BaseInteraction.d.ts

@@ -0,0 +1,78 @@
+import { ProgressTracker } from "./utilities/ProgressTracker";
+import { Variant } from "../shared/types";
+import { Validator } from "../types/Global";
+import { InteractionConfig, InteractionMechanic } from "../types/Interactions";
+import { InteractionData } from "../types/Data";
+import { NormalizedAssets } from "../types/Assets";
+import { AnimationsManager, SoundManager } from "../shared/managers";
+export type InteractionEventMap = {
+    'interaction:ready': CustomEvent<{
+        id: string;
+    }>;
+    'interaction:progress': CustomEvent<{
+        current: number;
+        total: number;
+        percentage: number;
+    }>;
+    'interaction:state-change': CustomEvent<{
+        state: any;
+        isComplete: boolean;
+    }>;
+    'interaction:complete': CustomEvent<{
+        state: any;
+        id: string;
+    }>;
+    'interaction:hint-shown': CustomEvent<{
+        message?: string;
+    }>;
+    'interaction:error': CustomEvent<{
+        error: Error;
+        message: string;
+    }>;
+};
+export declare abstract class BaseInteraction<T extends InteractionData> extends HTMLElement {
+    readonly id: string;
+    abstract readonly interactionMechanic: InteractionMechanic;
+    isValid: boolean;
+    implementsProgress: boolean;
+    protected data: T;
+    config: InteractionConfig;
+    protected assets: NormalizedAssets | null;
+    progressTracker: ProgressTracker;
+    protected animationsManager: AnimationsManager;
+    protected soundManager: SoundManager;
+    private _initialized;
+    errors: string;
+    constructor(data: T, config: InteractionConfig, assets?: NormalizedAssets | null, validator?: Validator);
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    abstract render(): void;
+    abstract getCurrentState(): any;
+    abstract isInteractionComplete(): boolean;
+    abstract onVariantChange(variant: Variant): void;
+    abstract onHint(): void;
+    protected initialize(): void;
+    protected cleanup(): void;
+    protected initializeProgress(total: number): void;
+    protected setProgress(current: number): void;
+    protected incrementProgress(): void;
+    protected decrementProgress(): void;
+    protected getProgress(): {
+        current: number;
+        total: number;
+        percentage: number;
+    };
+    private emitReady;
+    protected emitProgress(): void;
+    protected emitStateChange(): void;
+    protected emitComplete(): void;
+    protected emitHintShown(message?: string): void;
+    protected emitError(error: Error, message?: string): void;
+    onChange(newVariant: Variant): void;
+    setSteps(steps: number): void;
+    submit(): void;
+    hint(): void;
+    reset(): void;
+    set(variant: Variant): void;
+    get(): Variant;
+}

package/dist/core/index.d.ts

@@ -0,0 +1 @@
+export { BaseInteraction } from "./BaseInteraction";

package/dist/core/utilities/ProgressTracker.d.ts

@@ -0,0 +1,58 @@
+/**
+ * ProgressTracker - Utility for tracking interaction progress
+ *
+ * Shell-agnostic progress tracking that can be used by any interaction.
+ * Maintains current/total state and calculates percentage.
+ *
+ * @example
+ * ```typescript
+ * const tracker = new ProgressTracker();
+ * tracker.initialize(10);
+ * tracker.increment();  // current = 1
+ * tracker.getPercentage();  // 10
+ * ```
+ */
+export declare class ProgressTracker {
+    private _current;
+    _total: number;
+    /**
+     * Initialize tracker with total number of items
+     */
+    initialize(total: number): void;
+    /**
+     * Set current progress value
+     */
+    setCurrent(value: number): void;
+    /**
+     * Increment progress by 1
+     */
+    increment(): void;
+    /**
+     * Decrement progress by 1
+     */
+    decrement(): void;
+    /**
+     * Reset progress to 0
+     */
+    reset(): void;
+    /**
+     * Get progress percentage (0-100)
+     */
+    getPercentage(): number;
+    /**
+     * Check if progress is complete
+     */
+    isComplete(): boolean;
+    /**
+     * Get current value
+     */
+    get current(): number;
+    /**
+     * Get total value
+     */
+    get total(): number;
+    /**
+     * Get remaining items
+     */
+    get remaining(): number;
+}

package/dist/core/utilities/index.d.ts

@@ -0,0 +1 @@
+export { ProgressTracker } from './ProgressTracker';

package/dist/engines/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./tables";
+export * from "./text";

package/dist/engines/tables/implementation/graders.d.ts

@@ -0,0 +1,23 @@
+import { TableCompletion, TableState } from "../../../types/Tables";
+import { GradingResult } from "../../../types/Grading";
+import { CellGradingState } from "../../../types/Tables";
+export declare function naryTableGrader(answerKey: Map<string, string[]>, userData: TableCompletion, rows: string[]): GradingResult;
+export declare function lookupTableGrader(answerKey: TableState, userData: TableCompletion, rows: string[], cols: string[]): GradingResult;
+export declare function classificationTableGrader(answerKey: Map<string, string[]>, userData: TableCompletion, rows: string[], cols: string[]): GradingResult;
+export declare function adjacencyTableGrader(answerKey: TableState, userData: TableCompletion, rows: string[]): GradingResult;
+/**
+ * Generate per-cell grading state for adjacency tables
+ */
+export declare function getAdjacencyCellGrading(answerKey: TableState, userData: TableCompletion, rows: string[]): CellGradingState;
+/**
+ * Generate per-cell grading state for lookup tables
+ */
+export declare function getLookupCellGrading(answerKey: TableState, userData: TableCompletion, rows: string[], cols: string[]): CellGradingState;
+/**
+ * Generate per-cell grading state for classification tables
+ */
+export declare function getClassificationCellGrading(answerKey: Map<string, string[]>, userData: TableCompletion, rows: string[], cols: string[]): CellGradingState;
+/**
+ * Generate per-cell grading state for n-ary tables
+ */
+export declare function getNaryCellGrading(answerKey: Map<string, string[]>, userData: TableCompletion, rows: string[]): CellGradingState;

package/dist/engines/tables/implementation/index.d.ts

@@ -0,0 +1,4 @@
+export * from './parsers';
+export * from './validators';
+export * from './graders';
+export * from './utils';

package/dist/engines/tables/implementation/parsers.d.ts

@@ -0,0 +1,36 @@
+import { BaseTableData, ValueTableData } from "../../../types/Tables";
+type ParseResult = {
+    data: BaseTableData;
+    errors?: Record<string, string>;
+};
+type ValueTableParseResult = {
+    data: ValueTableData;
+    errors?: Record<string, string>;
+};
+/**
+ * The classification table presents a default configuration where we have non-equal rows and columns and
+ * participant is presented with check boxes on each cell to add 'attributes' to each row item.
+ *
+ * The n-ary table is just a superset or the former, with the discrepancies being using radio buttons instead
+ * (single selection) and not allowing row items to be in more than one category (this is handled in the
+ * n-ary table validator).
+ *
+ * For grading, we take the row item and the checked columns. Using the answerKey, we check if those columns
+ * that were selected contain the row item; correct if yes, wrong otherwise. If there are mixed correct/wrong,
+ * we just fractionate the grading n/100, where n = correct items.
+ *
+ * Classification Example - Notice repetitions
+ *
+ * WORK = Talk with my colleagues | Eat | Report Attendance;
+ * SCHOOL = Eat | Complete my examns | Play in the basketball club;
+ * HOME = Eat | Talk with my colleagues | Sleep;
+ *
+ * N-ARY example
+ *
+ * TRUE = Water is Blue | An active volcano is hot;
+ * FALSE = MJ was a piano player | Africa is above Europe | A chef is someone who writes poems
+ */
+export declare function basicTableDataParser(code: string): ParseResult;
+export declare function adjacencyTableDataParser(code: string): ValueTableParseResult;
+export declare function lookupTableDataParser(code: string): ValueTableParseResult;
+export {};

package/dist/engines/tables/implementation/utils.d.ts

@@ -0,0 +1,18 @@
+import { CellValue, CellKind, TableState } from "../../../types/Tables";
+/**
+ * Extract all values from a TableState answer key
+ */
+export declare function getAllValues(answerKey: TableState): CellValue[];
+/**
+ * Get all unique values from a TableState answer key
+ */
+export declare function getAllUniqueValues(answerKey: TableState): CellValue[];
+/**
+ * Auto-detect the best cell kind based on the values in the answer key
+ */
+export declare function detectCellKind(values: CellValue[]): CellKind;
+/**
+ * Compare two cell values for equality
+ * Handles string, number, and boolean comparisons
+ */
+export declare function compareValues(expected: CellValue, actual: CellValue): boolean;

package/dist/engines/tables/implementation/validators.d.ts

@@ -0,0 +1,9 @@
+import { BaseTableData, ValueTableData } from "../../../types/Tables";
+type ValidationResult = {
+    ok: boolean;
+    errors?: Record<string, string>;
+};
+export declare function basicTableDataValidator(data: BaseTableData, preset?: 'classification' | 'n-ary'): ValidationResult;
+export declare function adjacencyTableDataValidator(data: ValueTableData): ValidationResult;
+export declare function lookupTableDataValidator(data: ValueTableData): ValidationResult;
+export {};

package/dist/engines/tables/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./implementation";
+export { EduTable } from "./script";

package/dist/engines/tables/script.d.ts

@@ -0,0 +1,37 @@
+import { TableConfiguration, TableState, CellGradingState, TableCompletion } from "../../types/Tables";
+type EduTableElement = HTMLElement & {
+    config: TableConfiguration;
+    getValue(): TableState;
+    setValue(next: TableState): void;
+    getState(): TableCompletion;
+    reset(): void;
+};
+export declare class EduTable extends HTMLElement implements EduTableElement {
+    private _config;
+    private _state;
+    private _mounted;
+    static get observedAttributes(): string[];
+    private $wrapEl;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    set config(v: TableConfiguration);
+    get config(): TableConfiguration;
+    get value(): TableState;
+    set value(v: TableState);
+    getValue(): TableState;
+    setValue(next: TableState): void;
+    getState(): TableCompletion;
+    attributeChangedCallback(name: string, oldValue: string, newValue: string): void;
+    private initState;
+    private render;
+    private renderCell;
+    reset(): void;
+    setGradingState(gradingState: CellGradingState): void;
+    clearGradingState(): void;
+    private onChange;
+    private onInput;
+    private applyCellValue;
+    private emitChange;
+}
+export {};