@almadar/cli 0.3.1 → 0.3.3

package/shells/typescript-shell/packages/client/src/clients/kflow/molecules/learning/BloomQuizBlock.stories.tsx

@@ -0,0 +1,154 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { action } from "@storybook/addon-actions";
+import { BloomQuizBlock } from "./BloomQuizBlock";
+
+const meta: Meta<typeof BloomQuizBlock> = {
+  title: "KFlow/Molecules/Learning/BloomQuizBlock",
+  component: BloomQuizBlock,
+  parameters: {
+    layout: "padded",
+  },
+  tags: ["autodocs"],
+  argTypes: {
+    level: {
+      control: "select",
+      options: ["remember", "understand", "apply", "analyze", "evaluate", "create"],
+    },
+    isAnswered: {
+      control: "boolean",
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof BloomQuizBlock>;
+
+export const Remember: Story = {
+  args: {
+    level: "remember",
+    question: "What is the definition of photosynthesis?",
+    answer:
+      "Photosynthesis is the process by which plants and other organisms convert light energy into chemical energy that can be stored and later released to fuel the organism's activities.",
+    index: 0,
+    isAnswered: false,
+    conceptId: "concept-1",
+    onAnswer: action("UI:ANSWER_BLOOM"),
+  },
+};
+
+export const Understand: Story = {
+  args: {
+    level: "understand",
+    question:
+      "Explain in your own words how photosynthesis benefits the ecosystem.",
+    answer:
+      "Photosynthesis benefits the ecosystem in several ways:\n\n1. **Oxygen Production**: It releases oxygen as a byproduct, which is essential for aerobic organisms\n2. **Carbon Dioxide Removal**: It removes CO₂ from the atmosphere, helping regulate climate\n3. **Food Chain Foundation**: It creates glucose that forms the base of most food chains\n4. **Energy Conversion**: It transforms solar energy into chemical energy that can be used by other organisms",
+    index: 1,
+    isAnswered: false,
+    conceptId: "concept-1",
+    onAnswer: action("UI:ANSWER_BLOOM"),
+  },
+};
+
+export const Apply: Story = {
+  args: {
+    level: "apply",
+    question:
+      "Design a simple experiment to demonstrate that plants need light for photosynthesis.",
+    answer:
+      "**Experiment Design:**\n\n1. Take two identical plants of the same species\n2. Place one plant in sunlight and one in complete darkness\n3. Ensure both receive the same amount of water\n4. After one week, compare the plants\n5. The plant in darkness will show yellowing leaves and reduced growth, demonstrating that light is essential for photosynthesis",
+    index: 2,
+    isAnswered: false,
+    conceptId: "concept-1",
+    onAnswer: action("UI:ANSWER_BLOOM"),
+  },
+};
+
+export const Analyze: Story = {
+  args: {
+    level: "analyze",
+    question:
+      "Compare and contrast photosynthesis and cellular respiration. What is the relationship between these two processes?",
+    answer:
+      "**Comparison:**\n\n| Aspect | Photosynthesis | Cellular Respiration |\n|--------|---------------|---------------------|\n| Location | Chloroplasts | Mitochondria |\n| Reactants | CO₂ + H₂O + Light | Glucose + O₂ |\n| Products | Glucose + O₂ | CO₂ + H₂O + ATP |\n| Energy | Absorbed | Released |\n\n**Relationship:** These processes are complementary - the products of one are the reactants of the other, forming a cycle that sustains life on Earth.",
+    index: 3,
+    isAnswered: false,
+    conceptId: "concept-1",
+    onAnswer: action("UI:ANSWER_BLOOM"),
+  },
+};
+
+export const Evaluate: Story = {
+  args: {
+    level: "evaluate",
+    question:
+      "Assess the potential impact of deforestation on global photosynthesis rates and climate change. Is this a significant concern?",
+    answer:
+      "**Assessment:**\n\nDeforestation significantly impacts global photosynthesis and climate:\n\n1. **Reduced Carbon Sequestration**: Fewer trees means less CO₂ absorbed\n2. **Positive Feedback Loop**: Less photosynthesis → more atmospheric CO₂ → more warming → more forest fires → less photosynthesis\n3. **Oxygen Production**: While oceans produce most oxygen, forests are crucial for land-based ecosystems\n\n**Verdict:** This is a critical concern. The Amazon alone absorbs ~2 billion tons of CO₂ annually. Its destruction would accelerate climate change significantly.",
+    index: 4,
+    isAnswered: false,
+    conceptId: "concept-1",
+    onAnswer: action("UI:ANSWER_BLOOM"),
+  },
+};
+
+export const Create: Story = {
+  args: {
+    level: "create",
+    question:
+      "Design an artificial photosynthesis system that could be used to capture carbon dioxide and produce clean fuel. What components would it need?",
+    answer:
+      "**Artificial Photosynthesis System Design:**\n\n```\n┌─────────────────────────────────────────┐\n│         Light Harvesting Layer          │\n│    (Solar panels / Quantum dots)        │\n├─────────────────────────────────────────┤\n│         Catalyst Chamber                │\n│    (Cobalt/Manganese catalysts)         │\n├─────────────────────────────────────────┤\n│      CO₂ Capture Membrane               │\n├─────────────────────────────────────────┤\n│       Fuel Synthesis Unit               │\n│    (Hydrogen/Methanol production)       │\n└─────────────────────────────────────────┘\n```\n\n**Key Components:**\n1. Light absorbers (semiconductor materials)\n2. Water oxidation catalysts\n3. CO₂ reduction catalysts\n4. Proton exchange membrane\n5. Fuel collection system",
+    index: 5,
+    isAnswered: false,
+    conceptId: "concept-1",
+    onAnswer: action("UI:ANSWER_BLOOM"),
+  },
+};
+
+export const WithCodeQuestion: Story = {
+  args: {
+    level: "apply",
+    question:
+      "Given the following function, what will be the output?\n\n```python\ndef fibonacci(n):\n    if n <= 1:\n        return n\n    return fibonacci(n-1) + fibonacci(n-2)\n\nprint(fibonacci(6))\n```",
+    answer:
+      "The output will be `8`.\n\n**Explanation:**\n- fibonacci(6) = fibonacci(5) + fibonacci(4)\n- fibonacci(5) = 5, fibonacci(4) = 3\n- 5 + 3 = 8\n\nThe Fibonacci sequence: 0, 1, 1, 2, 3, 5, **8**, ...",
+    index: 0,
+    isAnswered: false,
+    conceptId: "concept-algorithms",
+    onAnswer: action("UI:ANSWER_BLOOM"),
+  },
+};
+
+export const Answered: Story = {
+  args: {
+    level: "understand",
+    question: "Explain the concept of recursion in programming.",
+    answer:
+      "Recursion is a programming technique where a function calls itself to solve a problem by breaking it down into smaller subproblems.",
+    index: 0,
+    isAnswered: true,
+    conceptId: "concept-recursion",
+    onAnswer: action("UI:ANSWER_BLOOM"),
+  },
+};
+
+export const AllLevels: Story = {
+  render: () => (
+    <div className="space-y-4">
+      {(["remember", "understand", "apply", "analyze", "evaluate", "create"] as const).map(
+        (level, index) => (
+          <BloomQuizBlock
+            key={level}
+            level={level}
+            question={`This is a ${level}-level question example.`}
+            answer={`This is the answer for the ${level}-level question.`}
+            index={index}
+            isAnswered={index < 2}
+            onAnswer={action(`UI:ANSWER_BLOOM_${level}`)}
+          />
+        )
+      )}
+    </div>
+  ),
+};

package/shells/typescript-shell/packages/client/src/clients/kflow/molecules/learning/BloomQuizBlock.tsx

@@ -0,0 +1,232 @@
+/**
+ * BloomQuizBlock Molecule Component
+ *
+ * Practice question component with Bloom's Taxonomy level indicator.
+ * Displays questions categorized by cognitive level (remember, understand,
+ * apply, analyze, evaluate, create).
+ *
+ * Event Contract:
+ * - Emits: UI:ANSWER_BLOOM { level, index, conceptId }
+ * - Emits: UI:REVEAL_ANSWER { level, index }
+ * - entityAware: true
+ */
+
+import React, { useState, useMemo } from "react";
+import { CheckCircle } from "lucide-react";
+import { Box } from "../../../../components/atoms/Box";
+import { Button } from "../../../../components/atoms/Button";
+import { Badge } from "../../../../components/atoms/Badge";
+import { Typography } from "../../../../components/atoms/Typography";
+import { Icon } from "../../../../components/atoms/Icon";
+import { Card } from "../../../../components/atoms/Card";
+import { HStack, VStack } from "../../../../components/atoms/Stack";
+import { useEventBus } from "../../../../hooks/useEventBus";
+import { CodeBlock } from "../markdown/CodeBlock";
+import { MarkdownContent } from "../markdown/MarkdownContent";
+import {
+  parseMarkdownWithCodeBlocks,
+  BloomLevel,
+} from "../../utils/parseLessonSegments";
+
+// Bloom's Taxonomy configuration with colors and labels
+export const BLOOM_CONFIG: Record<
+  BloomLevel,
+  {
+    color: string;
+    bgColor: string;
+    borderColor: string;
+    label: string;
+    icon: string;
+  }
+> = {
+  remember: {
+    color: "bg-gray-500",
+    bgColor: "bg-gray-50 dark:bg-gray-900/30",
+    borderColor: "border-gray-200 dark:border-gray-700",
+    label: "Remember",
+    icon: "📝",
+  },
+  understand: {
+    color: "bg-blue-500",
+    bgColor: "bg-blue-50 dark:bg-blue-900/30",
+    borderColor: "border-blue-200 dark:border-blue-700",
+    label: "Understand",
+    icon: "💡",
+  },
+  apply: {
+    color: "bg-green-500",
+    bgColor: "bg-green-50 dark:bg-green-900/30",
+    borderColor: "border-green-200 dark:border-green-700",
+    label: "Apply",
+    icon: "🔧",
+  },
+  analyze: {
+    color: "bg-yellow-500",
+    bgColor: "bg-yellow-50 dark:bg-yellow-900/30",
+    borderColor: "border-yellow-200 dark:border-yellow-700",
+    label: "Analyze",
+    icon: "🔍",
+  },
+  evaluate: {
+    color: "bg-orange-500",
+    bgColor: "bg-orange-50 dark:bg-orange-900/30",
+    borderColor: "border-orange-200 dark:border-orange-700",
+    label: "Evaluate",
+    icon: "⚖️",
+  },
+  create: {
+    color: "bg-purple-500",
+    bgColor: "bg-purple-50 dark:bg-purple-900/30",
+    borderColor: "border-purple-200 dark:border-purple-700",
+    label: "Create",
+    icon: "🎨",
+  },
+};
+
+export interface BloomQuizBlockProps {
+  /** Bloom's taxonomy level */
+  level: BloomLevel;
+  /** The question content (supports markdown) */
+  question: string;
+  /** The answer content (supports markdown) */
+  answer: string;
+  /** Question index for display */
+  index?: number;
+  /** Whether this question has been answered */
+  isAnswered?: boolean;
+  /** Concept ID for event payloads */
+  conceptId?: string;
+  /** Callback when answer is revealed */
+  onAnswer?: () => void;
+  /** Additional CSS classes */
+  className?: string;
+}
+
+export const BloomQuizBlock: React.FC<BloomQuizBlockProps> = ({
+  level,
+  question,
+  answer,
+  index,
+  isAnswered,
+  conceptId,
+  onAnswer,
+  className,
+}) => {
+  const eventBus = useEventBus();
+  const [revealed, setRevealed] = useState(false);
+  const config = BLOOM_CONFIG[level];
+
+  const questionSegments = useMemo(
+    () => parseMarkdownWithCodeBlocks(question),
+    [question],
+  );
+  const answerSegments = useMemo(
+    () => parseMarkdownWithCodeBlocks(answer),
+    [answer],
+  );
+
+  const handleReveal = () => {
+    if (!revealed) {
+      eventBus.emit("UI:ANSWER_BLOOM", {
+        entity: "Concept",
+        level,
+        index,
+        conceptId,
+      });
+      onAnswer?.();
+    }
+    eventBus.emit("UI:REVEAL_ANSWER", { level, index, revealed: !revealed });
+    setRevealed(!revealed);
+  };
+
+  return (
+    <Card
+      className={`${config.bgColor} ${config.borderColor} border ${className || ""}`}
+    >
+      <Box className="p-4">
+        <VStack gap="md">
+          {/* Header with question number and bloom level */}
+          <HStack justify="between" align="center" className="flex-wrap gap-2">
+            <HStack gap="sm" align="center">
+              {index !== undefined && (
+                <Typography
+                  variant="small"
+                  className="text-gray-500 dark:text-gray-400 font-medium"
+                >
+                  Question {index + 1}
+                </Typography>
+              )}
+              <Badge className={`${config.color} text-white`} size="sm">
+                {config.icon} {config.label}
+              </Badge>
+            </HStack>
+            {isAnswered && (
+              <Icon
+                icon={CheckCircle}
+                size="sm"
+                className="text-green-600 dark:text-green-400"
+              />
+            )}
+          </HStack>
+
+          {/* Question content */}
+          <Box className="font-semibold text-indigo-900 dark:text-indigo-200">
+            <VStack gap="sm">
+              {questionSegments.map((segment, idx) =>
+                segment.type === "markdown" ? (
+                  <MarkdownContent
+                    key={`q-md-${idx}`}
+                    content={segment.content}
+                  />
+                ) : (
+                  <CodeBlock
+                    key={`q-code-${idx}`}
+                    language={segment.language || "text"}
+                    code={segment.content}
+                  />
+                ),
+              )}
+            </VStack>
+          </Box>
+
+          {/* Reveal button */}
+          <Button variant="primary" size="sm" onClick={handleReveal}>
+            {revealed ? "Hide Answer" : "Reveal Answer"}
+          </Button>
+
+          {/* Answer content */}
+          {revealed && (
+            <Card className="bg-white/80 dark:bg-gray-800/80 border border-indigo-100 dark:border-indigo-800">
+              <Box className="p-3">
+                <VStack gap="sm">
+                  <Typography
+                    variant="small"
+                    className="text-gray-600 dark:text-gray-400 font-medium uppercase tracking-wide"
+                  >
+                    Answer:
+                  </Typography>
+                  {answerSegments.map((segment, idx) =>
+                    segment.type === "markdown" ? (
+                      <MarkdownContent
+                        key={`a-md-${idx}`}
+                        content={segment.content}
+                      />
+                    ) : (
+                      <CodeBlock
+                        key={`a-code-${idx}`}
+                        language={segment.language || "text"}
+                        code={segment.content}
+                      />
+                    ),
+                  )}
+                </VStack>
+              </Box>
+            </Card>
+          )}
+        </VStack>
+      </Box>
+    </Card>
+  );
+};
+
+BloomQuizBlock.displayName = "BloomQuizBlock";

package/shells/typescript-shell/packages/client/src/clients/kflow/molecules/learning/ConnectionBlock.stories.tsx

@@ -0,0 +1,57 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { ConnectionBlock } from "./ConnectionBlock";
+
+const meta: Meta<typeof ConnectionBlock> = {
+  title: "KFlow/Molecules/Learning/ConnectionBlock",
+  component: ConnectionBlock,
+  parameters: {
+    layout: "padded",
+  },
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof ConnectionBlock>;
+
+export const Default: Story = {
+  args: {
+    content:
+      "This concept builds on your understanding of **basic arithmetic** and **variables**. If you're comfortable with adding numbers and storing values, you're ready to learn about functions!",
+  },
+};
+
+export const WithList: Story = {
+  args: {
+    content: `This lesson connects to several concepts you've already learned:
+
+- **Variables**: You'll use variables to store intermediate results
+- **Conditionals**: Decision-making within loops
+- **Basic I/O**: Displaying loop results
+
+Think about how you might combine these to repeat an action multiple times.`,
+  },
+};
+
+export const MathConnection: Story = {
+  args: {
+    content:
+      "Remember how we calculated the area of a rectangle? The concept of **integration** extends this idea to find the area under curves. Instead of simple multiplication, we'll sum up infinitely small rectangles.",
+  },
+};
+
+export const ProgrammingConnection: Story = {
+  args: {
+    content: `Your knowledge of **arrays** and **loops** is essential here.
+
+When we discuss **sorting algorithms**, we're essentially asking: "How can we rearrange elements in an array efficiently?"
+
+The patterns you've seen in nested loops will help you understand how comparisons work in sorting.`,
+  },
+};
+
+export const RealWorldConnection: Story = {
+  args: {
+    content:
+      "Think about how you organize your music playlist or sort your emails by date. These everyday tasks use the same principles we'll explore in this lesson on **data structures**.",
+  },
+};

package/shells/typescript-shell/packages/client/src/clients/kflow/molecules/learning/ConnectionBlock.tsx

@@ -0,0 +1,60 @@
+/**
+ * ConnectionBlock Molecule Component
+ *
+ * Displays connections to prior knowledge, helping learners see how
+ * new concepts relate to what they already know.
+ *
+ * Event Contract:
+ * - No events emitted (display-only component)
+ * - entityAware: false
+ */
+
+import React from "react";
+import { Link2 } from "lucide-react";
+import { Box } from "../../../../components/atoms/Box";
+import { Typography } from "../../../../components/atoms/Typography";
+import { Icon } from "../../../../components/atoms/Icon";
+import { Card } from "../../../../components/atoms/Card";
+import { HStack, VStack } from "../../../../components/atoms/Stack";
+import { MarkdownContent } from "../markdown/MarkdownContent";
+
+export interface ConnectionBlockProps {
+  /** The connection content (supports markdown) */
+  content: string;
+  /** Additional CSS classes */
+  className?: string;
+}
+
+export const ConnectionBlock: React.FC<ConnectionBlockProps> = ({
+  content,
+  className,
+}) => {
+  return (
+    <Card
+      className={`bg-emerald-50 dark:bg-emerald-900/20 border-2 border-emerald-200 dark:border-emerald-800 ${className || ""}`}
+    >
+      <Box className="p-5">
+        <HStack gap="md" align="start">
+          <Icon
+            icon={Link2}
+            size="md"
+            className="text-emerald-600 dark:text-emerald-400 flex-shrink-0 mt-1"
+          />
+          <VStack gap="sm" className="flex-1">
+            <Typography
+              variant="h4"
+              className="font-semibold text-emerald-900 dark:text-emerald-100"
+            >
+              Building On What You Know
+            </Typography>
+            <Box className="text-gray-700 dark:text-gray-300">
+              <MarkdownContent content={content} />
+            </Box>
+          </VStack>
+        </HStack>
+      </Box>
+    </Card>
+  );
+};
+
+ConnectionBlock.displayName = "ConnectionBlock";

package/shells/typescript-shell/packages/client/src/clients/kflow/molecules/learning/QuizBlock.tsx

@@ -0,0 +1,138 @@
+/**
+ * QuizBlock Molecule Component
+ *
+ * Simple question/answer reveal component for embedded quizzes
+ * in lesson content. Unlike BloomQuizBlock, this doesn't have
+ * cognitive level classification.
+ *
+ * Event Contract:
+ * - Emits: UI:REVEAL_QUIZ { index, revealed }
+ * - entityAware: false
+ */
+
+import React, { useState, useMemo } from "react";
+import { Box } from "../../../../components/atoms/Box";
+import { Button } from "../../../../components/atoms/Button";
+import { Card } from "../../../../components/atoms/Card";
+import { VStack } from "../../../../components/atoms/Stack";
+import { Typography } from "../../../../components/atoms/Typography";
+import { useEventBus } from "../../../../hooks/useEventBus";
+import { CodeBlock } from "../markdown/CodeBlock";
+import { MarkdownContent } from "../markdown/MarkdownContent";
+import { parseMarkdownWithCodeBlocks } from "../../utils/parseLessonSegments";
+
+export interface QuizBlockProps {
+  /** The question content (supports markdown) */
+  question?: string;
+  /** The answer content (supports markdown) */
+  answer?: string;
+  /** Question index */
+  index?: number;
+  /** Additional CSS classes */
+  className?: string;
+  // Entity-aware props (for schema compatibility)
+  /** Entity type */
+  entity?: string;
+  /** Data to display */
+  data?: Record<string, unknown>;
+  /** Actions */
+  actions?: Array<{ label: string; event: string }>;
+  /** Item actions */
+  itemActions?: Array<{
+    label: string;
+    event: string;
+    onClick?: (row: Record<string, unknown>) => void;
+  }>;
+  /** Display variant */
+  variant?: string;
+  /** Show questions flag */
+  showQuestions?: boolean;
+  /** Fields to display */
+  displayFields?: string[];
+}
+
+export const QuizBlock: React.FC<QuizBlockProps> = ({
+  question = "",
+  answer = "",
+  index,
+  className,
+}) => {
+  const eventBus = useEventBus();
+  const [revealed, setRevealed] = useState(false);
+
+  const questionSegments = useMemo(
+    () => parseMarkdownWithCodeBlocks(question || ""),
+    [question],
+  );
+  const answerSegments = useMemo(
+    () => parseMarkdownWithCodeBlocks(answer || ""),
+    [answer],
+  );
+
+  const handleReveal = () => {
+    const newRevealed = !revealed;
+    eventBus.emit("UI:REVEAL_QUIZ", { index, revealed: newRevealed });
+    setRevealed(newRevealed);
+  };
+
+  return (
+    <Card
+      className={`bg-indigo-50/40 dark:bg-indigo-900/20 border border-indigo-100 dark:border-indigo-800 ${className || ""}`}
+    >
+      <Box className="p-4">
+        <VStack gap="md">
+          {/* Question */}
+          <Box className="font-semibold text-indigo-900 dark:text-indigo-200">
+            <VStack gap="sm">
+              {questionSegments.map((segment, idx) =>
+                segment.type === "markdown" ? (
+                  <MarkdownContent
+                    key={`q-md-${idx}`}
+                    content={segment.content}
+                  />
+                ) : (
+                  <CodeBlock
+                    key={`q-code-${idx}`}
+                    language={segment.language || "text"}
+                    code={segment.content}
+                  />
+                ),
+              )}
+            </VStack>
+          </Box>
+
+          {/* Reveal button */}
+          <Button variant="primary" size="sm" onClick={handleReveal}>
+            {revealed ? "Hide Answer" : "Reveal Answer"}
+          </Button>
+
+          {/* Answer */}
+          {revealed && (
+            <Card className="bg-white/80 dark:bg-gray-800/80 border border-indigo-100 dark:border-indigo-800">
+              <Box className="p-3">
+                <VStack gap="sm">
+                  {answerSegments.map((segment, idx) =>
+                    segment.type === "markdown" ? (
+                      <MarkdownContent
+                        key={`a-md-${idx}`}
+                        content={segment.content}
+                      />
+                    ) : (
+                      <CodeBlock
+                        key={`a-code-${idx}`}
+                        language={segment.language || "text"}
+                        code={segment.content}
+                      />
+                    ),
+                  )}
+                </VStack>
+              </Box>
+            </Card>
+          )}
+        </VStack>
+      </Box>
+    </Card>
+  );
+};
+
+QuizBlock.displayName = "QuizBlock";