cognikit 0.1.0

package/dist/interactions/sequential-classification/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * SEQUENTIAL CLASSIFICATION - Classify items one at a time
+ *
+ * interaction mechanics inspired from
+ * @see https://learningapps.org
+ */
+import { BaseInteraction } from "../../core/BaseInteraction";
+import { Variant } from "../../shared/types";
+import { InteractionConfig, InteractionMechanic } from "../../types/Interactions";
+import { NormalizedAssets } from "../../types/Assets";
+import { ClassificationData } from "../../types/Data";
+export declare class SequentialClassification extends BaseInteraction<ClassificationData> {
+    interactionMechanic: InteractionMechanic;
+    private categories;
+    private allItems;
+    private categorized;
+    private container;
+    private centerZone;
+    private zonesGrid;
+    private zones;
+    private chips;
+    private activeChip;
+    private currentZone;
+    private isDragging;
+    private startX;
+    private startY;
+    private offsetX;
+    private offsetY;
+    private boundPointerMove;
+    private boundPointerUp;
+    private variant;
+    constructor(data: ClassificationData, config: InteractionConfig, assets: NormalizedAssets | null);
+    protected initialize(): void;
+    protected cleanup(): void;
+    onVariantChange(newVariant: Variant): void;
+    render(): void;
+    private createDropZones;
+    private showNextChip;
+    private reparentChip;
+    private handlePointerDown;
+    private handlePointerMove;
+    private handlePointerUp;
+    private checkZoneOverlap;
+    getCurrentState(): any;
+    isInteractionComplete(): boolean;
+    onHint(): void;
+    submit(): void;
+    reset(): void;
+}

package/dist/interactions/shared/association-implementation/grader.d.ts

@@ -0,0 +1,3 @@
+import { AssociationData } from "../../../types/Data";
+import { GradingResult } from "../../../types/Grading";
+export declare function associationDataGrader(answerKey: AssociationData["pairs"], userData: Map<string, string>, parent: any): GradingResult;

package/dist/interactions/shared/association-implementation/index.d.ts

@@ -0,0 +1 @@
+export * from "./grader";

package/dist/interactions/shared/classification-implementation/grader.d.ts

@@ -0,0 +1,3 @@
+import { ClassificationData } from "../../../types/Data";
+import { GradingResult } from "../../../types/Grading";
+export declare function classificationGrader(correctData: ClassificationData["categories"], userData: Map<string, string>, els: any): GradingResult;

package/dist/interactions/shared/classification-implementation/index.d.ts

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

package/dist/interactions/shared/classification-implementation/parser.d.ts

@@ -0,0 +1,11 @@
+import { ParsingResult } from "../../../shared";
+/**
+ * Example
+ * ---
+ * RED FRUITS =  apple | strawberry | cherry;
+ * Yellow Fruits = banana | pineapple | mango;
+ * Green Fruits = watermelon | avocado;
+ * = coconut | eggplant;
+ * ---
+ */
+export declare function classificationParser(code: string): ParsingResult;

package/dist/interactions/shared/classification-implementation/validator.d.ts

@@ -0,0 +1,3 @@
+import { ValidationResult } from "../../../shared";
+import { ClassificationData } from "../../../types/Data";
+export declare function classificationValidator(data: ClassificationData): ValidationResult;

package/dist/interactions/simultaneous-association/index.d.ts

@@ -0,0 +1,34 @@
+import { BaseInteraction } from "../../core/BaseInteraction";
+import { Variant } from "../../shared/types";
+import { InteractionConfig, InteractionMechanic } from "../../types/Interactions";
+import { NormalizedAssets } from "../../types/Assets";
+import { AssociationData } from "../../types/Data";
+type SimultaneousAssociationSpec = {
+    rightColumnLabel: string;
+    leftColumnLabel: string;
+    layoutDirection: 'vertical' | 'horizontal';
+};
+export declare class SimultaneousAssociation extends BaseInteraction<AssociationData> {
+    interactionMechanic: InteractionMechanic;
+    private leftItems;
+    private rightItems;
+    private matched;
+    private matchColors;
+    private currentSelected;
+    private currentEl;
+    private currentColor;
+    private $leftCol;
+    private $rightCol;
+    constructor(data: AssociationData, config: InteractionConfig, assets: NormalizedAssets | null, spec: SimultaneousAssociationSpec | null);
+    protected initialize(): void;
+    protected cleanup(): void;
+    onVariantChange(newVariant: Variant): void;
+    render(): void;
+    private renderItems;
+    getCurrentState(): any;
+    isInteractionComplete(): boolean;
+    onHint(): void;
+    submit(): void;
+    reset(): void;
+}
+export {};

package/dist/interactions/text-transformation/index.d.ts

@@ -0,0 +1,2 @@
+export { TextTransformation } from "./static";
+export { SequentialTextTransformation, type SequentialTransformationExpectations } from "./sequential";

package/dist/interactions/text-transformation/sequential.d.ts

@@ -0,0 +1,37 @@
+import { BaseInteraction } from "../../core/BaseInteraction";
+import { Variant } from "../../shared/types";
+import { InteractionConfig, InteractionMechanic } from "../../types/Interactions";
+import { GradingResult } from "../../types/Grading";
+import { TextEngineSequentialInteractionData } from "../../types/Text";
+export type SequentialTransformationExpectations = Record<number, Record<number, string[]>>;
+export declare class SequentialTextTransformation extends BaseInteraction<TextEngineSequentialInteractionData> {
+    interactionMechanic: InteractionMechanic;
+    private _slides;
+    private _currentStep;
+    private _textConfig;
+    private _$text;
+    private _responses;
+    private _gradingByStep;
+    private _isGraded;
+    private _expectedByStep;
+    get slidesCount(): number;
+    constructor(data: TextEngineSequentialInteractionData, config: InteractionConfig, expectedByStep?: SequentialTransformationExpectations);
+    protected initialize(): void;
+    protected cleanup(): void;
+    onVariantChange(newVariant: Variant): void;
+    setSteps(stepIndex: number): void;
+    render(): void;
+    private getTotalTargetCount;
+    private buildDefaultExpectations;
+    private getExpectedForStep;
+    private saveCurrentStepResponse;
+    private getResponseForStep;
+    private updateProgressAcrossSteps;
+    getCurrentState(): any;
+    isInteractionComplete(): boolean;
+    onHint(): void;
+    grade(): GradingResult;
+    submit(): void;
+    reset(): void;
+    setExpectedTransformationsByStep(expectedByStep: SequentialTransformationExpectations): void;
+}

package/dist/interactions/text-transformation/static.d.ts

@@ -0,0 +1,47 @@
+import { BaseInteraction } from "../../core/BaseInteraction";
+import { Variant } from "../../shared/types";
+import { InteractionConfig, InteractionMechanic } from "../../types/Interactions";
+import { TextEngineBaseData } from "../../types/Text";
+import { type TextEngineBaseUserData } from "../../engines/text";
+/**
+ * Text Transformation Interaction
+ *
+ * Users edit highlighted text segments to transform them according to instructions.
+ * For example: convert present tense to past tense, singular to plural, etc.
+ *
+ * Example data:
+ * ```
+ * {
+ *   type: 'base',
+ *   parts: ['I', 'drink', 'water', 'every', 'day'],
+ *   targets: [
+ *     { words: ['drink'], startPos: 1, endPos: 1 }
+ *   ]
+ * }
+ * ```
+ *
+ * Expected transformations would be provided separately in config or instructions.
+ */
+export declare class TextTransformation extends BaseInteraction<TextEngineBaseData> {
+    interactionMechanic: InteractionMechanic;
+    private _textConfig;
+    private _$text;
+    private _expectedTransformations;
+    constructor(data: TextEngineBaseData, config: InteractionConfig, expectedTransformations?: Record<number, string[]>);
+    protected initialize(): void;
+    protected cleanup(): void;
+    onVariantChange(newVariant: Variant): void;
+    render(): void;
+    getCurrentState(): TextEngineBaseUserData;
+    isInteractionComplete(): boolean;
+    onHint(): void;
+    getUserData(): TextEngineBaseUserData;
+    submit(): void;
+    grade(): import("../../types").GradingResult;
+    reset(): void;
+    /**
+     * Set the expected transformations after construction
+     * Useful for dynamic configuration
+     */
+    setExpectedTransformations(transformations: Record<number, string[]>): void;
+}

package/dist/shared/assets.d.ts

@@ -0,0 +1,6 @@
+import { NormalizedAssets } from "../types/Assets";
+export declare class AssetValidationError extends Error {
+    issues: string[];
+    constructor(issues: string[]);
+}
+export declare function validateAndNormalizeAssets(input: unknown): NormalizedAssets;

package/dist/shared/dsl.d.ts

@@ -0,0 +1,9 @@
+import { GrammarParser } from "../types/Global";
+import { TextData, NumberData, SelectData, DateData, TimeData } from "../types/Input";
+export declare const parseTX: GrammarParser<TextData>;
+export declare const parseSL: GrammarParser<SelectData>;
+export declare const parseNM: GrammarParser<NumberData>;
+export declare const parseDT: GrammarParser<DateData>;
+export declare const parseTM: GrammarParser<TimeData>;
+export declare function isInteractionSequential(s: string): boolean;
+export declare function splitByDoubleSemiColon(s: string): string[];

package/dist/shared/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types";
+export * from "./utils";
+export * from "./managers";
+export * from "./assets";

package/dist/shared/managers/AnimationsManager.d.ts

@@ -0,0 +1,55 @@
+/**
+ * AnimationsManager - Utility for managing animations in Shadow DOM components
+ *
+ * Shadow DOM components cannot access keyframes defined in the main document.
+ * This manager injects keyframe definitions into Shadow DOM and provides
+ * a simple API to apply animations to elements.
+ */
+export type AnimationName = 'shake' | 'pulse-green' | 'bounce-in' | 'float' | 'rubber' | 'jello' | 'heartbeat' | 'shimmer' | 'wobble' | 'pop' | 'fade-slide' | 'swing' | 'orbit' | 'flash' | 'spin-pulse';
+export interface AnimationOptions {
+    duration?: string;
+    timing?: string;
+    iterations?: string | number;
+    delay?: string;
+}
+export declare class AnimationsManager {
+    private static injectedRoots;
+    isEnabled: boolean;
+    /**
+     * Inject keyframes into a Shadow DOM
+     * Call this once during component initialization
+     */
+    static injectKeyframes(shadowRoot: ShadowRoot): void;
+    /**
+     * Apply animation to an element
+     * @param element - The element to animate (can be in Shadow DOM)
+     * @param animationName - Name of the animation
+     * @param options - Optional animation configuration
+     */
+    animate(element: HTMLElement, animationName: AnimationName, options?: AnimationOptions): void;
+    /**
+     * Stop/clear animation on an element
+     */
+    stop(element: HTMLElement): void;
+    /**
+     * Animate element for a specific duration then auto-stop
+     * @param element - The element to animate
+     * @param animationName - Name of the animation
+     * @param durationMs - Duration in milliseconds before auto-stopping
+     * @param options - Optional animation configuration
+     */
+    animateFor(element: HTMLElement, animationName: AnimationName, durationMs: number, options?: AnimationOptions): void;
+    /**
+     * Get all available animation names
+     */
+    getAvailableAnimations(): AnimationName[];
+    /**
+     * Apply animation using CSS class (for hover/active states)
+     * Requires keyframes to be available in the component's Shadow DOM
+     */
+    addAnimationClass(element: HTMLElement, animationName: AnimationName): void;
+    /**
+     * Remove animation class
+     */
+    removeAnimationClass(element: HTMLElement, animationName: AnimationName): void;
+}

package/dist/shared/managers/SoundManager.d.ts

@@ -0,0 +1,78 @@
+/**
+ * SoundManager - Centralized audio playback utility
+ *
+ * Features:
+ * - Play local sounds from /public/assets/audio/
+ * - Play sounds from external URLs
+ * - Preload and cache audio for better performance
+ * - Volume control with fade effects
+ * - Error handling and fallbacks
+ */
+export type SoundName = 'success' | 'failure' | 'pop' | 'low-time' | 'start' | 'flip';
+export interface PlaySoundOptions {
+    volume?: number;
+    loop?: boolean;
+    fadeIn?: number;
+    fadeOut?: number;
+    playbackRate?: number;
+    onEnd?: () => void;
+    onError?: (error: Error) => void;
+}
+export declare class SoundManager {
+    isEnabled: boolean;
+    private audioCache;
+    private activeSounds;
+    private baseUrl;
+    private localSounds;
+    constructor();
+    /**
+     * Play a sound by name or URL
+     * @param soundNameOrUrl - Predefined sound name or full URL
+     * @param options - Playback options
+     */
+    playSound(soundNameOrUrl: SoundName | string, options?: PlaySoundOptions): Promise<void>;
+    /**
+     * Preload sounds for better performance
+     * @param sounds - Array of sound names or URLs to preload
+     */
+    preload(sounds: (SoundName | string)[]): Promise<void>;
+    /**
+     * Stop all currently playing sounds
+     */
+    stopAll(): void;
+    /**
+     * Stop a specific sound
+     * @param soundNameOrUrl - Sound to stop
+     */
+    stop(soundNameOrUrl: SoundName | string): void;
+    /**
+     * Clear the audio cache
+     */
+    clearCache(): void;
+    /**
+     * Set global volume for all future sounds
+     * @param volume - Volume level (0.0 to 1.0)
+     */
+    setGlobalVolume(volume: number): void;
+    /**
+     * Resolve sound name to full URL
+     */
+    private resolveUrl;
+    /**
+     * Get or create audio element
+     */
+    private getAudio;
+    /**
+     * Configure audio element with options
+     */
+    private configureAudio;
+    /**
+     * Play audio with error handling
+     */
+    private playAudio;
+    /**
+     * Fade volume over time
+     */
+    private fadeVolume;
+}
+export declare const soundManager: SoundManager;

package/dist/shared/managers/index.d.ts

@@ -0,0 +1,3 @@
+export { AnimationsManager } from "./AnimationsManager";
+export type { AnimationName, AnimationOptions } from "./AnimationsManager";
+export { SoundManager } from "./SoundManager";

package/dist/shared/types.d.ts

@@ -0,0 +1,25 @@
+import { InteractionData } from "../types/Data";
+export type Variant = 'elegant' | 'playful' | 'outline' | 'letter' | 'sign' | 'minimal' | 'glass' | 'empty';
+export type CognitiveOp = 'discrimination' | 'classification' | 'freerecall' | 'production' | 'association' | 'comparisson' | 'transformation' | 'seriation' | 'recognition' | 'cuedrecall' | 'evaluation';
+export interface Module {
+    id: string;
+    process: CognitiveOp;
+    implementation: {
+        parser(code: string): ParsingResult;
+        validator(data: InteractionData): ValidationResult;
+        interactions: Record<string, any>;
+    };
+    help: string;
+}
+export type ParsingResult = {
+    ok: boolean;
+    data?: InteractionData | null;
+    errors?: Record<string, string> | null;
+};
+export type ValidationResult = {
+    ok: boolean;
+    errors: Record<string, string> | null;
+};
+export type GrammarParser = (code: string) => GrammarParseResult;
+export type GrammarParseResult = ParsingResult;
+export type SimpleErrorObject = Record<string, string>;

package/dist/shared/utils.d.ts

@@ -0,0 +1,13 @@
+export declare const randomHexColorsList: string[];
+export declare function shuffle<T>(array: T[]): T[];
+export declare const hash: (str: string, seed?: number) => string;
+export declare function escapeHtml(s: string): string;
+export declare function parseYamlAssets(yamlText: string): unknown;
+export declare function isString(v: unknown): v is string;
+export declare function isNumber(v: unknown): v is number;
+export declare function looksLikeTime(s: string): boolean;
+export declare function typeOf(v: unknown): string;
+export declare function isPlainObject(v: unknown): v is Record<string, unknown>;
+export declare function splitByPipes(input: string): string[];
+export declare const dedupe: <T>(arr: T[]) => T[];
+export declare function isOneOf<const T extends readonly string[]>(value: string, allowed: T): value is T[number];

package/dist/shell/index.d.ts

@@ -0,0 +1 @@
+export { InteractionsBaseShell } from "./simple-shell";

package/dist/shell/simple-shell/index.d.ts

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

package/dist/shell/simple-shell/script.d.ts

@@ -0,0 +1,61 @@
+import { BaseInteraction } from "../../core/BaseInteraction";
+import { InteractionData } from "../../types/Data";
+export declare class InteractionsBaseShell extends HTMLElement {
+    static get observedAttributes(): string[];
+    private soundManager;
+    private animationsManager;
+    private $titleEl;
+    private $promptBtn;
+    private $timerEl;
+    private $headerEl;
+    private $footerEl;
+    private $contentEl;
+    private $checkBtn;
+    private $seeAnswersBtn;
+    private $scoresBtn;
+    private $retryBtn;
+    private $radioNav;
+    private $progressContainer;
+    private $progressBar;
+    private $progressIcon;
+    private $progressCounter;
+    private $interactionScreen;
+    private $errorContent;
+    private $attemptsMessage;
+    private $scoreDisplay;
+    private $timerDisplay;
+    private interaction?;
+    private timerInterval;
+    private remainingSeconds;
+    private interactionComplete;
+    private attemptCount;
+    private attemptLimit;
+    private currentScreen;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string, newValue: string): void;
+    setInteraction<T extends InteractionData>(interaction: BaseInteraction<T>): void;
+    removeInteraction(): void;
+    private setupShellListeners;
+    private setupInteractionListeners;
+    private removeInteractionListeners;
+    private updateProgress;
+    private handleCompletion;
+    private handleGraded;
+    private reset;
+    private handleRetry;
+    private openPromptDialog;
+    private switchScreen;
+    private startTimer;
+    private stopTimer;
+    private getFormattedTime;
+    private updateTimerDisplay;
+    private handleTimerComplete;
+    pauseTimer(): void;
+    resumeTimer(): void;
+    resetTimer(): void;
+    private updateVisibility;
+    private renderRadioNav;
+    getContentArea(): HTMLElement;
+}

package/dist/types/Assets.d.ts

@@ -0,0 +1,40 @@
+export type AssetType = "image" | "video" | "audio" | "html" | "tts";
+export type AssetRegistryInput = Record<string, unknown>;
+export interface BaseAsset {
+    id: string;
+    type: AssetType;
+    dialog?: boolean;
+}
+export interface ImageAsset extends BaseAsset {
+    type: "image";
+    url: string;
+    size?: "small" | "medium" | "large" | string;
+}
+export interface AudioAsset extends BaseAsset {
+    type: "audio";
+    url: string;
+    volume?: number;
+}
+export interface VideoAsset extends BaseAsset {
+    type: "video";
+    url: string;
+    span?: {
+        from: string;
+        to: string;
+    };
+    source?: 'general' | 'youtube';
+}
+export interface HtmlAsset extends BaseAsset {
+    type: "html";
+    content: string;
+}
+export interface TtsAsset extends BaseAsset {
+    type: "tts";
+    content: string;
+    volume?: number;
+}
+export type Asset = ImageAsset | AudioAsset | VideoAsset | HtmlAsset | TtsAsset;
+export interface NormalizedAssets {
+    assetsById: Record<string, Asset>;
+    assetsList: Asset[];
+}

package/dist/types/Data.d.ts

@@ -0,0 +1,32 @@
+import { BaseTableData, ValueTableData } from "./Tables";
+import { TextEngineBaseData, TextEngineBlanksData, TextEngineClassificationData, TextEngineSequentialInteractionData } from "./Text";
+export type InteractionData = ClassificationData | AssociationData | BaseTableData | ValueTableData | TextEngineBaseData | TextEngineBlanksData | TextEngineClassificationData | TextEngineSequentialInteractionData | FreeRecallData | RecognitionData | SeriationData;
+export type ClassificationData = {
+    type: 'classification';
+    categories: {
+        label: string;
+        items: string[];
+    }[];
+    distractors?: string[];
+};
+export type AssociationData = {
+    type: 'association';
+    pairs: {
+        left: string;
+        right: string;
+    }[];
+    distractors?: string[];
+};
+export type SeriationData = {
+    type: 'seriation';
+    items: string[];
+};
+export type FreeRecallData = SeriationData;
+export interface RecognitionData {
+    type: 'recognition';
+    data: {
+        question: string;
+        correctOptions: string[];
+        options: string[];
+    }[];
+}

package/dist/types/Global.d.ts

@@ -0,0 +1,24 @@
+import { InteractionData } from "./Data";
+import { InputElementData } from "./Input";
+export type StyleVariant = 'elegant' | 'playful' | 'outline' | 'letter' | 'sign' | 'minimal' | 'card' | 'glass' | 'empty';
+export type CognitiveOperation = 'discrimination' | 'classification' | 'freerecall' | 'production' | 'association' | 'comparisson' | 'transformation' | 'seriation' | 'recognition' | 'cuedrecall' | 'evaluation';
+export type ParsingResult = {
+    ok: boolean;
+    data?: InteractionData | null;
+    errors?: Record<string, string> | null;
+};
+export type ValidationResult = {
+    ok: boolean;
+    errors: Record<string, string> | null;
+};
+type DataTypesUnion = InteractionData | InputElementData;
+export type GrammarParseResult<T extends DataTypesUnion = DataTypesUnion> = {
+    ok: boolean;
+    data?: T | null;
+    errors?: SimpleErrorObject | SimpleErrorObject[] | null;
+};
+export type SimpleErrorObject = Record<string, string>;
+export type ComplexErrorObject = SimpleErrorObject[];
+export type GrammarParser<T extends DataTypesUnion = DataTypesUnion> = (code: string) => GrammarParseResult<T>;
+export type Validator = (data: InteractionData) => ValidationResult;
+export {};

package/dist/types/Grading.d.ts

@@ -0,0 +1,8 @@
+export type GradingResult = {
+    score: number;
+    correct: number;
+    total: number;
+    answerKey?: any;
+    userResponse?: any;
+};
+export type GradingState = 'correct' | 'wrong' | 'missed';

package/dist/types/Input.d.ts

@@ -0,0 +1,35 @@
+export type InputModality = 'text' | 'number' | 'select' | 'date' | 'time';
+export type InputElementReference = 'tx' | 'nm' | 'sl' | 'dt' | 'tm';
+export type MediaRenference = 'im' | 'au' | 'tt' | 'vi' | 'ht';
+export type InputElementData = TextData | NumberData | SelectData | DateData | TimeData;
+interface InputElementBaseData {
+    type: InputModality;
+    id: string;
+    html: string;
+}
+export interface TextData extends InputElementBaseData {
+    type: 'text';
+    value: string[];
+}
+export interface NumberData extends InputElementBaseData {
+    type: 'number';
+    targets: number[];
+    ranges?: {
+        from: number;
+        to: number;
+    }[];
+}
+export interface SelectData extends InputElementBaseData {
+    type: 'select';
+    correctOptions: string[];
+    options: string[];
+}
+export interface DateData extends InputElementBaseData {
+    type: 'date';
+    value: string;
+}
+export interface TimeData extends InputElementBaseData {
+    type: 'time';
+    value: string;
+}
+export {};

package/dist/types/Interactions.d.ts

@@ -0,0 +1,28 @@
+import { Variant } from "../shared/types";
+import { InteractionData } from "./Data";
+import { AssetType } from "./Assets";
+export type InteractionMechanic = 'static' | 'sequential' | 'automatic-sequencing' | 'prefers-horizontal-overflow' | 'prefers-vertical-overflow' | 'implements-open-canvas' | 'game';
+export type IInteractionSpec = unknown;
+export type InteractionConfig = {
+    prompt: string;
+    promptModality?: AssetType;
+    promptData?: string;
+    promptDataSpec?: string;
+    variant: Variant;
+    shuffle: boolean;
+    construct?: string;
+    playStaggeringAnimation?: boolean;
+    animationsEnabled?: boolean;
+    soundEnabled?: boolean;
+    inLineFeedback?: boolean;
+    immediateFeedback?: boolean;
+    attemptLimit: number | null;
+    timer: number | null;
+};
+export type IInteraction = {
+    id: string;
+    name: string;
+    data?: InteractionData;
+    css: string;
+    examples: Record<string, string>;
+};