@almadar/cli 0.3.2 → 0.3.3

package/shells/typescript-shell/packages/client/src/clients/kflow/organisms/NoteList.tsx

@@ -0,0 +1,209 @@
+/**
+ * NoteList Organism Component
+ *
+ * A hierarchical list of notes with expand/collapse and selection.
+ *
+ * Event Contract:
+ * - Emits events from NoteListItem children
+ * - entityAware: true
+ */
+
+import React from "react";
+import { Box } from "../../../components/atoms/Box";
+import { VStack } from "../../../components/atoms/Stack";
+import { Typography } from "../../../components/atoms/Typography";
+import { Spinner } from "../../../components/atoms/Spinner";
+import { NoteListItem, NoteData } from "../molecules/NoteListItem";
+import { useEventBus } from "../../../hooks/useEventBus";
+
+export interface NoteListProps {
+  /** Array of notes to display */
+  notes: NoteData[];
+  /** Currently selected note ID */
+  selectedNoteId?: string;
+  /** Show full content in items */
+  showFullContent?: boolean;
+  /** Loading state */
+  isLoading?: boolean;
+  /** Error state */
+  error?: Error | null;
+  /** Callback when note is selected */
+  onSelectNote?: (note: NoteData) => void;
+  /** Callback when note is deleted */
+  onDeleteNote?: (noteId: string) => void;
+  /** Callback when note edit is requested */
+  onEditNote?: (note: NoteData) => void;
+  /** Callback when note expand is toggled */
+  onToggleExpand?: (noteId: string) => void;
+  /** Callback when add child is clicked */
+  onAddChild?: (parentNoteId: string) => void;
+  /** Empty state message */
+  emptyMessage?: string;
+  /** Additional CSS classes */
+  className?: string;
+}
+
+// Helper to build tree structure from flat list
+function buildNoteTree(
+  notes: NoteData[],
+  parentId: string | null = null,
+  level: number = 0,
+): NoteData[] {
+  // If notes already have proper structure with children, use as-is
+  if (notes.length > 0 && notes[0].hasChildren !== undefined) {
+    return notes;
+  }
+
+  // Otherwise, assume flat list at root level
+  return notes.map((note) => ({
+    ...note,
+    level,
+    hasChildren: false,
+  }));
+}
+
+// Recursive component to render note tree
+const NoteTreeItem: React.FC<{
+  note: NoteData;
+  notes: NoteData[];
+  selectedNoteId?: string;
+  showFullContent: boolean;
+  onSelectNote?: (note: NoteData) => void;
+  onDeleteNote?: (noteId: string) => void;
+  onEditNote?: (note: NoteData) => void;
+  onToggleExpand?: (noteId: string) => void;
+  onAddChild?: (parentNoteId: string) => void;
+  depth: number;
+}> = ({
+  note,
+  notes,
+  selectedNoteId,
+  showFullContent,
+  onSelectNote,
+  onDeleteNote,
+  onEditNote,
+  onToggleExpand,
+  onAddChild,
+  depth,
+}) => {
+  // Find children for this note (if any)
+  const childNotes = notes.filter((n) => (n as any).parentId === note.id);
+
+  return (
+    <NoteListItem
+      note={{
+        ...note,
+        hasChildren: childNotes.length > 0,
+      }}
+      isSelected={selectedNoteId === note.id}
+      depth={depth}
+      showFullContent={showFullContent}
+      onSelect={onSelectNote}
+      onDelete={onDeleteNote}
+      onEdit={onEditNote}
+      onToggleExpand={onToggleExpand}
+      onAddChild={onAddChild}
+    >
+      {note.isExpanded &&
+        childNotes.map((child) => (
+          <NoteTreeItem
+            key={child.id}
+            note={child}
+            notes={notes}
+            selectedNoteId={selectedNoteId}
+            showFullContent={showFullContent}
+            onSelectNote={onSelectNote}
+            onDeleteNote={onDeleteNote}
+            onEditNote={onEditNote}
+            onToggleExpand={onToggleExpand}
+            onAddChild={onAddChild}
+            depth={depth + 1}
+          />
+        ))}
+    </NoteListItem>
+  );
+};
+
+export const NoteList: React.FC<NoteListProps> = ({
+  notes,
+  selectedNoteId,
+  showFullContent = false,
+  isLoading = false,
+  error = null,
+  onSelectNote,
+  onDeleteNote,
+  onEditNote,
+  onToggleExpand,
+  onAddChild,
+  emptyMessage = "No notes yet. Create one to get started!",
+  className,
+}) => {
+  const eventBus = useEventBus();
+
+  // Loading state
+  if (isLoading) {
+    return (
+      <Box
+        className={`flex items-center justify-center py-12 ${className || ""}`}
+      >
+        <VStack gap="md" align="center">
+          <Spinner size="lg" />
+          <Typography variant="body" className="text-gray-500">
+            Loading notes...
+          </Typography>
+        </VStack>
+      </Box>
+    );
+  }
+
+  // Error state
+  if (error) {
+    return (
+      <Box className={`py-8 ${className || ""}`}>
+        <Typography variant="body" className="text-red-500 text-center">
+          Error loading notes: {error.message}
+        </Typography>
+      </Box>
+    );
+  }
+
+  // Empty state
+  if (notes.length === 0) {
+    return (
+      <Box className={`py-12 ${className || ""}`}>
+        <VStack gap="md" align="center">
+          <Typography variant="body" className="text-gray-500 text-center">
+            {emptyMessage}
+          </Typography>
+        </VStack>
+      </Box>
+    );
+  }
+
+  // Get root-level notes (those without a parentId or at level 0)
+  const rootNotes = notes.filter((n) => !(n as any).parentId || n.level === 0);
+
+  return (
+    <Box className={className}>
+      <VStack gap="sm">
+        {rootNotes.map((note) => (
+          <NoteTreeItem
+            key={note.id}
+            note={note}
+            notes={notes}
+            selectedNoteId={selectedNoteId}
+            showFullContent={showFullContent}
+            onSelectNote={onSelectNote}
+            onDeleteNote={onDeleteNote}
+            onEditNote={onEditNote}
+            onToggleExpand={onToggleExpand}
+            onAddChild={onAddChild}
+            depth={0}
+          />
+        ))}
+      </VStack>
+    </Box>
+  );
+};
+
+NoteList.displayName = "NoteList";

package/shells/typescript-shell/packages/client/src/clients/kflow/organisms/SegmentRenderer.stories.tsx

@@ -0,0 +1,238 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { action } from "@storybook/addon-actions";
+import { SegmentRenderer } from "./SegmentRenderer";
+import { Segment } from "../utils/parseLessonSegments";
+
+const meta: Meta<typeof SegmentRenderer> = {
+  title: "KFlow/Organisms/SegmentRenderer",
+  component: SegmentRenderer,
+  parameters: {
+    layout: "padded",
+  },
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof SegmentRenderer>;
+
+const simpleSegments: Segment[] = [
+  {
+    type: "markdown",
+    content: `# Introduction to Functions
+
+Functions are one of the fundamental building blocks in programming. They allow you to:
+
+- **Encapsulate** code that performs a specific task
+- **Reuse** that code throughout your program
+- **Organize** your code into logical units`,
+  },
+  {
+    type: "code",
+    language: "javascript",
+    content: `function greet(name) {
+  return \`Hello, \${name}!\`;
+}
+
+console.log(greet("World")); // Output: Hello, World!`,
+  },
+  {
+    type: "markdown",
+    content: `Notice how the function takes a **parameter** called \`name\` and uses it to create a personalized greeting.`,
+  },
+];
+
+const fullLessonSegments: Segment[] = [
+  {
+    type: "activate",
+    question:
+      "Think about tasks you do repeatedly every day. How might grouping related actions together make them easier to remember and perform?",
+  },
+  {
+    type: "connect",
+    content:
+      "This lesson builds on your understanding of **variables** and **data types**. Functions use these concepts but add a new layer of organization to your code.",
+  },
+  {
+    type: "markdown",
+    content: `# Understanding Functions
+
+A function is a reusable block of code designed to perform a particular task. Functions help us:
+
+1. Write **DRY** (Don't Repeat Yourself) code
+2. Break complex problems into smaller parts
+3. Make code more readable and maintainable`,
+  },
+  {
+    type: "code",
+    language: "python",
+    content: `def calculate_area(width, height):
+    """Calculate the area of a rectangle."""
+    return width * height
+
+# Using the function
+room_area = calculate_area(10, 12)
+print(f"The room area is {room_area} square feet")`,
+  },
+  {
+    type: "reflect",
+    prompt:
+      "How might using functions change the way you approach writing a program? Think about a project you've worked on that could benefit from functions.",
+  },
+  {
+    type: "markdown",
+    content: `## Function Parameters
+
+Parameters are variables that act as placeholders for the values that will be passed to the function when it's called.`,
+  },
+  {
+    type: "bloom",
+    level: "remember",
+    question: "What are the two main parts of a function definition?",
+    answer:
+      "The two main parts are:\n1. **Function signature** - includes the function name and parameters\n2. **Function body** - the code that executes when the function is called",
+  },
+  {
+    type: "bloom",
+    level: "apply",
+    question:
+      "Write a function that takes two numbers and returns their average.",
+    answer: `\`\`\`python
+def average(a, b):
+    return (a + b) / 2
+
+# Test
+print(average(10, 20))  # Output: 15.0
+\`\`\``,
+  },
+];
+
+const quizOnlySegments: Segment[] = [
+  {
+    type: "markdown",
+    content: "## Quick Quiz\n\nTest your understanding with these questions:",
+  },
+  {
+    type: "quiz",
+    question: "What keyword is used to define a function in Python?",
+    answer: "The `def` keyword is used to define functions in Python.",
+  },
+  {
+    type: "quiz",
+    question:
+      "What is the difference between a parameter and an argument?",
+    answer:
+      "A **parameter** is the variable in the function definition, while an **argument** is the actual value passed to the function when it's called.",
+  },
+];
+
+export const SimpleLesson: Story = {
+  args: {
+    segments: simpleSegments,
+    conceptId: "concept-functions-intro",
+    onSaveActivation: action("UI:SAVE_ACTIVATION"),
+    onSaveReflection: action("UI:SAVE_REFLECTION"),
+    onAnswerBloom: action("UI:ANSWER_BLOOM"),
+  },
+};
+
+export const FullLesson: Story = {
+  args: {
+    segments: fullLessonSegments,
+    conceptId: "concept-functions-full",
+    onSaveActivation: action("UI:SAVE_ACTIVATION"),
+    onSaveReflection: action("UI:SAVE_REFLECTION"),
+    onAnswerBloom: action("UI:ANSWER_BLOOM"),
+  },
+};
+
+export const WithUserProgress: Story = {
+  args: {
+    segments: fullLessonSegments,
+    conceptId: "concept-functions-full",
+    userProgress: {
+      activationResponse:
+        "I brush my teeth the same way every morning - it's like a routine or function!",
+      reflectionNotes: [
+        "I think functions would help me avoid copy-pasting code when I need to do the same calculation multiple times.",
+      ],
+      bloomAnswered: { 0: true },
+    },
+    onSaveActivation: action("UI:SAVE_ACTIVATION"),
+    onSaveReflection: action("UI:SAVE_REFLECTION"),
+    onAnswerBloom: action("UI:ANSWER_BLOOM"),
+  },
+};
+
+export const QuizOnly: Story = {
+  args: {
+    segments: quizOnlySegments,
+    conceptId: "concept-quiz",
+  },
+};
+
+export const MarkdownOnly: Story = {
+  args: {
+    segments: [
+      {
+        type: "markdown",
+        content: `# Pure Markdown Content
+
+This example shows the SegmentRenderer with only markdown content.
+
+## Features
+
+- **Bold text** and *italic text*
+- Lists like this one
+- Code like \`console.log()\`
+
+## Tables
+
+| Feature | Supported |
+|---------|-----------|
+| Headers | Yes |
+| Bold | Yes |
+| Tables | Yes |
+
+> Blockquotes are also supported!`,
+      },
+    ],
+  },
+};
+
+export const CodeHeavy: Story = {
+  args: {
+    segments: [
+      {
+        type: "markdown",
+        content: "## Multiple Code Examples\n\nHere are examples in different languages:",
+      },
+      {
+        type: "code",
+        language: "javascript",
+        content: `// JavaScript
+const sum = (a, b) => a + b;`,
+      },
+      {
+        type: "code",
+        language: "python",
+        content: `# Python
+def sum(a, b):
+    return a + b`,
+      },
+      {
+        type: "code",
+        language: "rust",
+        content: `// Rust
+fn sum(a: i32, b: i32) -> i32 {
+    a + b
+}`,
+      },
+    ],
+  },
+};
+
+export const Empty: Story = {
+  args: {
+    segments: [],
+  },
+};

package/shells/typescript-shell/packages/client/src/clients/kflow/organisms/SegmentRenderer.tsx

@@ -0,0 +1,196 @@
+/**
+ * SegmentRenderer Organism Component
+ *
+ * Renders a list of lesson segments including markdown, code blocks,
+ * quizzes, and learning science components (activation, connection,
+ * reflection, bloom).
+ *
+ * Event Contract:
+ * - Emits events from child components (ActivationBlock, ReflectionBlock, BloomQuizBlock, etc.)
+ * - entityAware: true
+ */
+
+import React from "react";
+import { Box } from "../../../components/atoms/Box";
+import { VStack } from "../../../components/atoms/Stack";
+import { CodeBlock } from "../molecules/markdown/CodeBlock";
+import { MarkdownContent } from "../molecules/markdown/MarkdownContent";
+import { ActivationBlock } from "../molecules/learning/ActivationBlock";
+import { ConnectionBlock } from "../molecules/learning/ConnectionBlock";
+import { ReflectionBlock } from "../molecules/learning/ReflectionBlock";
+import { BloomQuizBlock } from "../molecules/learning/BloomQuizBlock";
+import { QuizBlock } from "../molecules/learning/QuizBlock";
+import { Segment, BloomLevel } from "../utils/parseLessonSegments";
+
+export interface UserProgress {
+  /** Saved activation response */
+  activationResponse?: string;
+  /** Saved reflection notes by index */
+  reflectionNotes?: string[];
+  /** Bloom questions answered by index */
+  bloomAnswered?: Record<number, boolean>;
+}
+
+export interface SegmentRendererProps {
+  /** Array of segments to render */
+  segments?: Segment[];
+  /** Concept ID for event payloads */
+  conceptId?: string;
+  /** User progress tracking data */
+  userProgress?: UserProgress;
+  /** Callback when activation response is saved */
+  onSaveActivation?: (response: string) => void;
+  /** Callback when reflection note is saved */
+  onSaveReflection?: (index: number, note: string) => void;
+  /** Callback when bloom question is answered */
+  onAnswerBloom?: (index: number, level: BloomLevel) => void;
+  /** Additional CSS classes for container */
+  className?: string;
+  /** Additional CSS classes for inner wrapper */
+  containerClassName?: string;
+  // Entity-aware props (for schema compatibility)
+  /** Entity type */
+  entity?: string;
+  /** Data array */
+  data?: unknown[];
+  /** Display variant */
+  variant?: string;
+  /** Item actions */
+  itemActions?: Array<{
+    label: string;
+    event: string;
+    onClick?: (row: Record<string, unknown>) => void;
+  }>;
+  /** Fields to display */
+  displayFields?: string[];
+  /** Show content flag */
+  showContent?: boolean;
+  /** Show lessons flag */
+  showLessons?: boolean;
+  /** Show progress flag */
+  showProgress?: boolean;
+  /** Actions */
+  actions?: Array<{ label: string; event: string }>;
+  /** Show modules flag */
+  showModules?: boolean;
+}
+
+export const SegmentRenderer: React.FC<SegmentRendererProps> = ({
+  segments = [],
+  conceptId,
+  userProgress,
+  onSaveActivation,
+  onSaveReflection,
+  onAnswerBloom,
+  className,
+  containerClassName = "border border-gray-200 dark:border-gray-700 rounded-lg p-4 md:p-6 overflow-x-auto",
+}) => {
+  if (!segments || segments.length === 0) {
+    return null;
+  }
+
+  // Track indices for reflect and bloom segments
+  let reflectIndex = 0;
+  let bloomIndex = 0;
+
+  return (
+    <Box className={className}>
+      <Box className={containerClassName}>
+        <VStack gap="lg">
+          {segments.map((segment, index) => {
+            if (segment.type === "markdown") {
+              return (
+                <MarkdownContent
+                  key={`md-${index}`}
+                  content={segment.content}
+                />
+              );
+            }
+
+            if (segment.type === "code") {
+              return (
+                <CodeBlock
+                  key={`code-${index}`}
+                  language={segment.language}
+                  code={segment.content}
+                />
+              );
+            }
+
+            if (segment.type === "quiz") {
+              return (
+                <QuizBlock
+                  key={`quiz-${index}`}
+                  question={segment.question}
+                  answer={segment.answer}
+                  index={index}
+                />
+              );
+            }
+
+            if (segment.type === "activate") {
+              return (
+                <ActivationBlock
+                  key={`activate-${index}`}
+                  question={segment.question}
+                  savedResponse={userProgress?.activationResponse}
+                  conceptId={conceptId}
+                  onSave={onSaveActivation}
+                />
+              );
+            }
+
+            if (segment.type === "connect") {
+              return (
+                <ConnectionBlock
+                  key={`connect-${index}`}
+                  content={segment.content}
+                />
+              );
+            }
+
+            if (segment.type === "reflect") {
+              const currentReflectIndex = reflectIndex++;
+              return (
+                <ReflectionBlock
+                  key={`reflect-${index}`}
+                  prompt={segment.prompt}
+                  index={currentReflectIndex}
+                  savedNote={
+                    userProgress?.reflectionNotes?.[currentReflectIndex]
+                  }
+                  conceptId={conceptId}
+                  onSave={(note) =>
+                    onSaveReflection?.(currentReflectIndex, note)
+                  }
+                />
+              );
+            }
+
+            if (segment.type === "bloom") {
+              const currentBloomIndex = bloomIndex++;
+              return (
+                <BloomQuizBlock
+                  key={`bloom-${index}`}
+                  level={segment.level}
+                  question={segment.question}
+                  answer={segment.answer}
+                  index={currentBloomIndex}
+                  isAnswered={userProgress?.bloomAnswered?.[currentBloomIndex]}
+                  conceptId={conceptId}
+                  onAnswer={() =>
+                    onAnswerBloom?.(currentBloomIndex, segment.level)
+                  }
+                />
+              );
+            }
+
+            return null;
+          })}
+        </VStack>
+      </Box>
+    </Box>
+  );
+};
+
+SegmentRenderer.displayName = "SegmentRenderer";

package/shells/typescript-shell/packages/client/src/clients/kflow/organisms/index.ts

@@ -0,0 +1,18 @@
+// Learning content
+export * from './SegmentRenderer';
+
+// Graph visualization
+export * from './ForceDirectedGraph';
+
+// Mindmap
+export * from './MindMapCanvas';
+
+// Notes
+export * from './NoteList';
+
+// Concept display
+export * from './ConceptCard';
+
+// Flashcards
+export * from './FlashCard';
+export * from './FlashCardStack';