@almadar/ui 5.32.2 → 5.33.0

package/dist/components/core/molecules/ActivationBlock.d.ts

@@ -0,0 +1,22 @@
+/**
+ * ActivationBlock Molecule Component
+ *
+ * Pre-lesson activation prompt. Invites learners to surface prior knowledge
+ * before content begins. Emits `UI:SAVE_ACTIVATION { response }`.
+ *
+ * Event Contract:
+ * - Emits: UI:SAVE_ACTIVATION { response }
+ * - entityAware: false
+ */
+import React from 'react';
+export interface ActivationBlockProps {
+    /** The prior-knowledge question */
+    question: string;
+    /** Pre-filled response from saved state */
+    savedResponse?: string;
+    /** Event name emitted on save/skip (as `UI:<saveEvent>`). Defaults to 'SAVE_ACTIVATION'. */
+    saveEvent?: string;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const ActivationBlock: React.FC<ActivationBlockProps>;

package/dist/components/core/molecules/BloomQuizBlock.d.ts

@@ -0,0 +1,25 @@
+/**
+ * BloomQuizBlock Molecule Component
+ *
+ * Practice Q&A with Bloom's Taxonomy level badge. Emits `UI:ANSWER_BLOOM { index, level }`.
+ *
+ * Event Contract:
+ * - Emits: UI:ANSWER_BLOOM { index, level }
+ * - entityAware: false
+ */
+import React from 'react';
+export type BloomLevel = 'remember' | 'understand' | 'apply' | 'analyze' | 'evaluate' | 'create';
+export interface BloomQuizBlockProps {
+    level: BloomLevel;
+    question: string;
+    answer: string;
+    /** Zero-based index (used in the emitted event payload) */
+    index?: number;
+    /** Whether the learner has already answered */
+    isAnswered?: boolean;
+    /** Event name emitted on first reveal (as `UI:<answerEvent>`). Defaults to 'ANSWER_BLOOM'. */
+    answerEvent?: string;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const BloomQuizBlock: React.FC<BloomQuizBlockProps>;

package/dist/components/core/molecules/ConnectionBlock.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ConnectionBlock Molecule Component
+ *
+ * Surfaces prior-knowledge connections before new content.
+ * Renders arbitrary markdown via MarkdownContent.
+ *
+ * Event Contract:
+ * - No events emitted (display-only)
+ * - entityAware: false
+ */
+import React from 'react';
+export interface ConnectionBlockProps {
+    /** Markdown content summarising what the learner already knows */
+    content: string;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const ConnectionBlock: React.FC<ConnectionBlockProps>;

package/dist/components/core/molecules/ReflectionBlock.d.ts

@@ -0,0 +1,23 @@
+/**
+ * ReflectionBlock Molecule Component
+ *
+ * Inline reflection prompt for deep processing. Emits `UI:SAVE_REFLECTION { index, note }`.
+ *
+ * Event Contract:
+ * - Emits: UI:SAVE_REFLECTION { index, note }
+ * - entityAware: false
+ */
+import React from 'react';
+export interface ReflectionBlockProps {
+    /** The reflection prompt */
+    prompt: string;
+    /** Zero-based index of this block (used in the emitted event payload) */
+    index: number;
+    /** Pre-filled note from saved state */
+    savedNote?: string;
+    /** Event name emitted on save (as `UI:<saveEvent>`). Defaults to 'SAVE_REFLECTION'. */
+    saveEvent?: string;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const ReflectionBlock: React.FC<ReflectionBlockProps>;

package/dist/components/core/molecules/index.d.ts

@@ -125,3 +125,9 @@ export { Chart, type ChartProps, type ChartType, type ChartSeries, } from "./Cha
 export { SignaturePad, type SignaturePadProps, } from "./SignaturePad";
 export { DocumentViewer, type DocumentViewerProps, type DocumentType, } from "./DocumentViewer";
 export { GraphCanvas, type GraphCanvasProps, type GraphNode, type GraphEdge, } from "./GraphCanvas";
+export { ActivationBlock, type ActivationBlockProps } from './ActivationBlock';
+export { ReflectionBlock, type ReflectionBlockProps } from './ReflectionBlock';
+export { ConnectionBlock, type ConnectionBlockProps } from './ConnectionBlock';
+export { BloomQuizBlock, type BloomQuizBlockProps, type BloomLevel } from './BloomQuizBlock';
+export { parseLessonSegments, type LessonSegment, type LessonUserProgress } from './parseLessonSegments';
+export { parseMarkdownWithCodeBlocks, type MixedSegment } from './lessonSegmentUtils';

package/dist/components/core/molecules/lessonSegmentUtils.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Utility for lesson-segment parsing: splits a markdown string into alternating
+ * markdown and fenced-code-block segments. Exported so SegmentRenderer and
+ * BloomQuizBlock can reuse without circular imports.
+ */
+export type MarkdownSegment = {
+    type: 'markdown';
+    content: string;
+};
+export type CodeSegment = {
+    type: 'code';
+    language: string;
+    content: string;
+    runnable?: boolean;
+};
+export type MixedSegment = MarkdownSegment | CodeSegment;
+/** Splits markdown content into markdown and fenced-code-block segments. */
+export declare function parseMarkdownWithCodeBlocks(content: string): MixedSegment[];

package/dist/components/core/molecules/parseLessonSegments.d.ts

@@ -0,0 +1,43 @@
+/**
+ * parseLessonSegments — parses lesson markdown with embedded learning-science
+ * XML-style tags into a typed Segment array.
+ *
+ * Supported tags: <activate>, <connect>, <reflect>, <bloom level="...">,
+ * <question>/<answer>, <visualize type="..." description="..." />.
+ *
+ * Tags may be open (unclosed) — the parser falls back to consuming content
+ * until the next recognised tag, a section heading (`\n\n#`), or end-of-input.
+ */
+import type { BloomLevel } from './BloomQuizBlock';
+import { type MixedSegment } from './lessonSegmentUtils';
+export type LessonSegment = MixedSegment | {
+    type: 'quiz';
+    question: string;
+    answer: string;
+} | {
+    type: 'activate';
+    question: string;
+} | {
+    type: 'connect';
+    content: string;
+} | {
+    type: 'reflect';
+    prompt: string;
+} | {
+    type: 'bloom';
+    level: BloomLevel;
+    question: string;
+    answer: string;
+} | {
+    type: 'visualization';
+    visualizationType: 'chart' | 'simulation';
+    description: string;
+};
+/** User progress state passed into SegmentRenderer. */
+export interface LessonUserProgress {
+    activationResponse?: string;
+    reflectionNotes?: string[];
+    bloomAnswered?: Record<number, boolean>;
+}
+/** Parse a lesson string into typed segments. Returns `[]` when input is empty. */
+export declare function parseLessonSegments(lesson: string | undefined): LessonSegment[];

package/dist/components/core/organisms/CodeRunnerPanel.d.ts

@@ -0,0 +1,42 @@
+/**
+ * CodeRunnerPanel Organism Component
+ *
+ * Editable code block with Run/Reset buttons and simulated terminal output.
+ * Real execution is a future concern; callers supply a simulation function via
+ * `onRun`. Emits `UI:RUN_CODE { language, exitCode }` on every run attempt.
+ *
+ * Event Contract:
+ * - Emits: UI:RUN_CODE { language, exitCode, error? }
+ * - entityAware: false
+ */
+import React from 'react';
+export interface CodeSimulationOutput {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    testResults: Array<{
+        input: string;
+        expectedOutput: string;
+        actualOutput: string;
+        passed: boolean;
+    }>;
+}
+export interface CodeRunnerPanelProps {
+    /** Initial code content */
+    code: string;
+    /** Programming language for syntax highlighting */
+    language: string;
+    /** Whether the panel allows running (false = read-only code block) */
+    runnable?: boolean;
+    /**
+     * Simulate executing the code. Omit to render a read-only block.
+     * Real execution is a separate future track — this callback supplies
+     * deterministic simulated output for UI feedback.
+     */
+    onRun?: (code: string) => Promise<CodeSimulationOutput>;
+    /** Event name to emit on run (emitted as `UI:<runEvent>`). Defaults to 'RUN_CODE'. */
+    runEvent?: string;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare const CodeRunnerPanel: React.FC<CodeRunnerPanelProps>;

package/dist/components/core/organisms/SegmentRenderer.d.ts

@@ -0,0 +1,38 @@
+/**
+ * SegmentRenderer Organism Component
+ *
+ * Renders a parsed array of LessonSegments — markdown, code, quizzes,
+ * activation prompts, connections, reflections, Bloom questions.
+ * The `visualization` segment type is passed through as a no-op unless the
+ * caller provides `onRenderVisualization` (future extensibility hook).
+ *
+ * Event Contract:
+ * - Delegates to child molecules: UI:SAVE_ACTIVATION, UI:SAVE_REFLECTION, UI:ANSWER_BLOOM
+ * - entityAware: false
+ */
+import React from 'react';
+import { type CodeSimulationOutput } from './CodeRunnerPanel';
+import type { LessonSegment, LessonUserProgress } from '../molecules/parseLessonSegments';
+export type { LessonSegment, LessonUserProgress, CodeSimulationOutput };
+export interface SegmentRendererProps {
+    /** Parsed lesson segments (see `parseLessonSegments`) */
+    segments: LessonSegment[];
+    /** Additional CSS classes for the root container */
+    className?: string;
+    /** CSS classes for the outer wrapping div */
+    containerClassName?: string;
+    /** User progress for restoring activation/reflection state */
+    userProgress?: LessonUserProgress;
+    /**
+     * Simulate executing runnable code blocks. Omit to render runnable blocks
+     * as read-only. Real execution is a future track.
+     */
+    onRunCodeSimulation?: (code: string, language: string) => Promise<CodeSimulationOutput>;
+    /**
+     * Optional render slot for `visualization` segment types. When not provided,
+     * visualization segments are silently skipped. Callers can wire this to any
+     * custom component or orbital generator.
+     */
+    onRenderVisualization?: (type: 'chart' | 'simulation', description: string, index: number) => React.ReactNode;
+}
+export declare const SegmentRenderer: React.FC<SegmentRendererProps>;

package/dist/components/core/organisms/index.d.ts

@@ -26,3 +26,5 @@ export { StepFlowOrganism, type StepFlowOrganismProps, } from "../../marketing/o
 export { ShowcaseOrganism, type ShowcaseOrganismProps, } from "../../marketing/organisms/ShowcaseOrganism";
 export { TeamOrganism, type TeamOrganismProps, } from "../../marketing/organisms/TeamOrganism";
 export { CaseStudyOrganism, type CaseStudyOrganismProps, } from "../../marketing/organisms/CaseStudyOrganism";
+export { CodeRunnerPanel, type CodeRunnerPanelProps, type CodeSimulationOutput, } from './CodeRunnerPanel';
+export { SegmentRenderer, type SegmentRendererProps, } from './SegmentRenderer';