@almadar/cli 0.3.2 → 1.0.3

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

@@ -0,0 +1,90 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { action } from "@storybook/addon-actions";
+import { ReflectionBlock } from "./ReflectionBlock";
+
+const meta: Meta<typeof ReflectionBlock> = {
+  title: "KFlow/Molecules/Learning/ReflectionBlock",
+  component: ReflectionBlock,
+  parameters: {
+    layout: "padded",
+  },
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj<typeof ReflectionBlock>;
+
+export const Default: Story = {
+  args: {
+    prompt:
+      "How might you apply what you've just learned about functions to simplify code you've written before?",
+    index: 0,
+    conceptId: "concept-functions-1",
+    onSave: action("UI:SAVE_REFLECTION"),
+  },
+};
+
+export const WithSavedNote: Story = {
+  args: {
+    prompt:
+      "How might you apply what you've just learned about functions to simplify code you've written before?",
+    index: 0,
+    savedNote:
+      "I realized I could refactor my calculator program to use functions for each operation instead of repeating the same code pattern.",
+    conceptId: "concept-functions-1",
+    onSave: action("UI:SAVE_REFLECTION"),
+  },
+};
+
+export const MathReflection: Story = {
+  args: {
+    prompt:
+      "Think about where you might encounter derivatives in everyday life. What quantities change with respect to other quantities?",
+    index: 1,
+    conceptId: "concept-calculus-1",
+    onSave: action("UI:SAVE_REFLECTION"),
+  },
+};
+
+export const ProgrammingReflection: Story = {
+  args: {
+    prompt:
+      "Consider the trade-offs between the sorting algorithms we've discussed. When would you choose one over another?",
+    index: 2,
+    conceptId: "concept-sorting-1",
+    onSave: action("UI:SAVE_REFLECTION"),
+  },
+};
+
+export const DeepReflection: Story = {
+  args: {
+    prompt:
+      "We've covered a lot of ground in this section. What concept challenged your previous assumptions the most? Why do you think that is?",
+    index: 3,
+    conceptId: "concept-advanced-1",
+    onSave: action("UI:SAVE_REFLECTION"),
+  },
+};
+
+export const MultipleReflections: Story = {
+  render: () => (
+    <div className="space-y-4">
+      <ReflectionBlock
+        prompt="What patterns do you notice in the examples we've seen?"
+        index={0}
+        onSave={action("UI:SAVE_REFLECTION_0")}
+      />
+      <ReflectionBlock
+        prompt="How does this connect to what you learned in the previous section?"
+        index={1}
+        savedNote="The recursion pattern here is similar to the tree traversal we studied before."
+        onSave={action("UI:SAVE_REFLECTION_1")}
+      />
+      <ReflectionBlock
+        prompt="What questions do you still have about this topic?"
+        index={2}
+        onSave={action("UI:SAVE_REFLECTION_2")}
+      />
+    </div>
+  ),
+};

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

@@ -0,0 +1,151 @@
+/**
+ * ReflectionBlock Molecule Component
+ *
+ * Post-section reflection prompt that encourages learners to pause
+ * and think about what they've learned.
+ *
+ * Event Contract:
+ * - Emits: UI:SAVE_REFLECTION { prompt, note, index, conceptId }
+ * - entityAware: true
+ */
+
+import React, { useState } from "react";
+import { PauseCircle } from "lucide-react";
+import { Box } from "../../../../components/atoms/Box";
+import { Button } from "../../../../components/atoms/Button";
+import { Textarea } from "../../../../components/atoms/Textarea";
+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";
+
+export interface ReflectionBlockProps {
+  /** The reflection prompt */
+  prompt: string;
+  /** Index of this reflection in the lesson */
+  index?: number;
+  /** Previously saved note (from entity) */
+  savedNote?: string;
+  /** Concept ID for event payloads */
+  conceptId?: string;
+  /** Callback when note is saved */
+  onSave?: (note: string) => void;
+  /** Additional CSS classes */
+  className?: string;
+}
+
+export const ReflectionBlock: React.FC<ReflectionBlockProps> = ({
+  prompt,
+  index,
+  savedNote,
+  conceptId,
+  onSave,
+  className,
+}) => {
+  const eventBus = useEventBus();
+  const [note, setNote] = useState(savedNote || "");
+  const [isExpanded, setIsExpanded] = useState(!savedNote);
+
+  const handleSave = () => {
+    eventBus.emit("UI:SAVE_REFLECTION", {
+      entity: "Concept",
+      conceptId,
+      prompt,
+      note,
+      index,
+    });
+    onSave?.(note);
+    setIsExpanded(false);
+  };
+
+  return (
+    <Card
+      className={`bg-amber-50 dark:bg-amber-900/20 border-2 border-amber-200 dark:border-amber-800 ${className || ""}`}
+    >
+      <Box className="p-5">
+        <HStack gap="md" align="start">
+          <Icon
+            icon={PauseCircle}
+            size="md"
+            className="text-amber-600 dark:text-amber-400 flex-shrink-0 mt-1"
+          />
+          <VStack gap="sm" className="flex-1">
+            <Typography
+              variant="h4"
+              className="font-semibold text-amber-900 dark:text-amber-100"
+            >
+              Pause & Reflect
+              {index !== undefined && (
+                <span className="text-amber-600 dark:text-amber-400 text-sm font-normal ml-2">
+                  #{index + 1}
+                </span>
+              )}
+            </Typography>
+            <Typography
+              variant="body"
+              className="text-gray-700 dark:text-gray-300 italic"
+            >
+              {prompt}
+            </Typography>
+
+            {isExpanded ? (
+              <VStack gap="md" className="w-full mt-2">
+                <Textarea
+                  placeholder="Write your thoughts here..."
+                  value={note}
+                  onChange={(e) => setNote(e.target.value)}
+                  rows={3}
+                  className="w-full border-amber-300 dark:border-amber-700 focus:ring-amber-500"
+                />
+                <HStack gap="sm">
+                  <Button variant="primary" onClick={handleSave}>
+                    Save Reflection
+                  </Button>
+                  <Button variant="ghost" onClick={() => setIsExpanded(false)}>
+                    Skip
+                  </Button>
+                </HStack>
+              </VStack>
+            ) : savedNote ? (
+              <VStack gap="sm" className="w-full mt-2">
+                <Box className="bg-white/60 dark:bg-gray-800/60 rounded-md p-3 border border-amber-200 dark:border-amber-700">
+                  <Typography
+                    variant="small"
+                    className="text-gray-600 dark:text-gray-400"
+                  >
+                    Your reflection:
+                  </Typography>
+                  <Typography
+                    variant="body"
+                    className="text-gray-800 dark:text-gray-200 mt-1"
+                  >
+                    {savedNote}
+                  </Typography>
+                </Box>
+                <Button
+                  variant="ghost"
+                  onClick={() => setIsExpanded(true)}
+                  className="text-amber-600 dark:text-amber-400 p-0"
+                >
+                  Edit reflection
+                </Button>
+              </VStack>
+            ) : (
+              <Button
+                variant="ghost"
+                size="sm"
+                onClick={() => setIsExpanded(true)}
+                className="text-amber-600 dark:text-amber-400"
+              >
+                Add your thoughts
+              </Button>
+            )}
+          </VStack>
+        </HStack>
+      </Box>
+    </Card>
+  );
+};
+
+ReflectionBlock.displayName = "ReflectionBlock";

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

@@ -0,0 +1,14 @@
+export { ActivationBlock } from "./ActivationBlock";
+export type { ActivationBlockProps } from "./ActivationBlock";
+
+export { BloomQuizBlock, BLOOM_CONFIG } from "./BloomQuizBlock";
+export type { BloomQuizBlockProps } from "./BloomQuizBlock";
+
+export { ConnectionBlock } from "./ConnectionBlock";
+export type { ConnectionBlockProps } from "./ConnectionBlock";
+
+export { ReflectionBlock } from "./ReflectionBlock";
+export type { ReflectionBlockProps } from "./ReflectionBlock";
+
+export { QuizBlock } from "./QuizBlock";
+export type { QuizBlockProps } from "./QuizBlock";

package/shells/typescript-shell/packages/client/src/clients/kflow/molecules/markdown/CodeBlock.stories.tsx

@@ -0,0 +1,188 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { CodeBlock } from "./CodeBlock";
+
+const meta: Meta<typeof CodeBlock> = {
+  title: "KFlow/Molecules/Markdown/CodeBlock",
+  component: CodeBlock,
+  parameters: {
+    layout: "padded",
+  },
+  tags: ["autodocs"],
+  argTypes: {
+    language: {
+      control: "select",
+      options: [
+        "javascript",
+        "typescript",
+        "python",
+        "rust",
+        "go",
+        "html",
+        "css",
+        "json",
+        "bash",
+        "text",
+      ],
+    },
+    showCopyButton: {
+      control: "boolean",
+    },
+    showLanguageBadge: {
+      control: "boolean",
+    },
+    maxHeight: {
+      control: "text",
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof CodeBlock>;
+
+const javascriptCode = `function fibonacci(n) {
+  if (n <= 1) return n;
+  return fibonacci(n - 1) + fibonacci(n - 2);
+}
+
+// Calculate the 10th Fibonacci number
+const result = fibonacci(10);
+console.log(result); // Output: 55`;
+
+const typescriptCode = `interface User {
+  id: string;
+  name: string;
+  email: string;
+  role: "admin" | "user" | "guest";
+}
+
+function greetUser(user: User): string {
+  return \`Hello, \${user.name}! You are logged in as \${user.role}.\`;
+}
+
+const user: User = {
+  id: "1",
+  name: "Alice",
+  email: "alice@example.com",
+  role: "admin",
+};
+
+console.log(greetUser(user));`;
+
+const pythonCode = `def quicksort(arr):
+    if len(arr) <= 1:
+        return arr
+    pivot = arr[len(arr) // 2]
+    left = [x for x in arr if x < pivot]
+    middle = [x for x in arr if x == pivot]
+    right = [x for x in arr if x > pivot]
+    return quicksort(left) + middle + quicksort(right)
+
+# Example usage
+numbers = [3, 6, 8, 10, 1, 2, 1]
+print(quicksort(numbers))`;
+
+const rustCode = `fn main() {
+    let numbers = vec![1, 2, 3, 4, 5];
+
+    let sum: i32 = numbers
+        .iter()
+        .filter(|&x| x % 2 == 0)
+        .map(|x| x * 2)
+        .sum();
+
+    println!("Sum of doubled even numbers: {}", sum);
+}`;
+
+export const JavaScript: Story = {
+  args: {
+    code: javascriptCode,
+    language: "javascript",
+    showCopyButton: true,
+    showLanguageBadge: true,
+  },
+};
+
+export const TypeScript: Story = {
+  args: {
+    code: typescriptCode,
+    language: "typescript",
+    showCopyButton: true,
+    showLanguageBadge: true,
+  },
+};
+
+export const Python: Story = {
+  args: {
+    code: pythonCode,
+    language: "python",
+    showCopyButton: true,
+    showLanguageBadge: true,
+  },
+};
+
+export const Rust: Story = {
+  args: {
+    code: rustCode,
+    language: "rust",
+    showCopyButton: true,
+    showLanguageBadge: true,
+  },
+};
+
+export const NoCopyButton: Story = {
+  args: {
+    code: javascriptCode,
+    language: "javascript",
+    showCopyButton: false,
+    showLanguageBadge: true,
+  },
+};
+
+export const NoLanguageBadge: Story = {
+  args: {
+    code: javascriptCode,
+    language: "javascript",
+    showCopyButton: true,
+    showLanguageBadge: false,
+  },
+};
+
+export const MinimalView: Story = {
+  args: {
+    code: javascriptCode,
+    language: "javascript",
+    showCopyButton: false,
+    showLanguageBadge: false,
+  },
+};
+
+export const LimitedHeight: Story = {
+  args: {
+    code: `// A very long code block
+${Array(50).fill('console.log("Line of code");').join("\n")}`,
+    language: "javascript",
+    showCopyButton: true,
+    showLanguageBadge: true,
+    maxHeight: "200px",
+  },
+};
+
+export const JsonExample: Story = {
+  args: {
+    code: globalThis.JSON.stringify(
+      {
+        name: "kflow",
+        version: "1.0.0",
+        dependencies: {
+          react: "^18.0.0",
+          typescript: "^5.0.0",
+        },
+      },
+      null,
+      2,
+    ),
+    language: "json",
+    showCopyButton: true,
+    showLanguageBadge: true,
+  },
+};

package/shells/typescript-shell/packages/client/src/clients/kflow/molecules/markdown/CodeBlock.tsx

@@ -0,0 +1,165 @@
+/**
+ * CodeBlock Molecule Component
+ *
+ * A syntax-highlighted code block with copy-to-clipboard functionality.
+ * Preserves scroll position during re-renders.
+ *
+ * Event Contract:
+ * - Emits: UI:COPY_CODE { language, success }
+ */
+
+import React, { useState, useRef, useLayoutEffect, useEffect } from "react";
+import { Prism as SyntaxHighlighter } from "react-syntax-highlighter";
+import { vscDarkPlus as dark } from "react-syntax-highlighter/dist/cjs/styles/prism";
+import { Copy, Check } from "lucide-react";
+import { Box } from "../../../../components/atoms/Box";
+import { Button } from "../../../../components/atoms/Button";
+import { Badge } from "../../../../components/atoms/Badge";
+import { HStack } from "../../../../components/atoms/Stack";
+import { useEventBus } from "../../../../hooks/useEventBus";
+
+export interface CodeBlockProps {
+  /** The code content to display */
+  code: string;
+  /** Programming language for syntax highlighting */
+  language?: string;
+  /** Show the copy button */
+  showCopyButton?: boolean;
+  /** Show the language badge */
+  showLanguageBadge?: boolean;
+  /** Maximum height before scrolling */
+  maxHeight?: string;
+  /** Additional CSS classes */
+  className?: string;
+}
+
+export const CodeBlock = React.memo<CodeBlockProps>(
+  ({
+    code,
+    language = "text",
+    showCopyButton = true,
+    showLanguageBadge = true,
+    maxHeight = "60vh",
+    className,
+  }) => {
+    const eventBus = useEventBus();
+    const scrollRef = useRef<HTMLDivElement | null>(null);
+    const savedScrollLeftRef = useRef<number>(0);
+    const [copied, setCopied] = useState(false);
+
+    // Save scrollLeft before updates
+    useLayoutEffect(() => {
+      const el = scrollRef.current;
+      return () => {
+        if (el) savedScrollLeftRef.current = el.scrollLeft;
+      };
+    }, [language, code]);
+
+    // Restore scrollLeft after updates
+    useLayoutEffect(() => {
+      const el = scrollRef.current;
+      if (el) el.scrollLeft = savedScrollLeftRef.current;
+    }, [language, code]);
+
+    // Native scroll listener to keep position updated
+    useEffect(() => {
+      const el = scrollRef.current;
+      if (!el) return;
+      const handle = () => {
+        savedScrollLeftRef.current = el.scrollLeft;
+      };
+      el.addEventListener("scroll", handle, { passive: true });
+      return () => el.removeEventListener("scroll", handle);
+    }, [language, code]);
+
+    // Copy to clipboard handler
+    const handleCopy = async () => {
+      try {
+        await navigator.clipboard.writeText(code);
+        setCopied(true);
+        eventBus.emit("UI:COPY_CODE", { language, success: true });
+        setTimeout(() => setCopied(false), 2000);
+      } catch (err) {
+        console.error("Failed to copy code:", err);
+        eventBus.emit("UI:COPY_CODE", { language, success: false });
+      }
+    };
+
+    return (
+      <Box className={`relative group ${className || ""}`}>
+        {/* Header with language badge and copy button */}
+        {(showLanguageBadge || showCopyButton) && (
+          <HStack
+            justify="between"
+            align="center"
+            className="px-3 py-2 bg-gray-800 rounded-t-lg border-b border-gray-700"
+          >
+            {showLanguageBadge && (
+              <Badge variant="default" size="sm">
+                {language}
+              </Badge>
+            )}
+            {showCopyButton && (
+              <Button
+                variant="ghost"
+                size="sm"
+                onClick={handleCopy}
+                className="opacity-0 group-hover:opacity-100 focus:opacity-100 transition-opacity text-gray-400 hover:text-white"
+                aria-label="Copy code"
+              >
+                {copied ? (
+                  <Check size={16} className="text-green-400" />
+                ) : (
+                  <Copy size={16} />
+                )}
+              </Button>
+            )}
+          </HStack>
+        )}
+
+        {/* Code content */}
+        <div
+          ref={scrollRef}
+          style={{
+            overflowX: "auto",
+            overflowY: "auto",
+            WebkitOverflowScrolling: "touch",
+            maxHeight,
+            overscrollBehavior: "auto",
+            touchAction: "pan-x pan-y",
+            contain: "paint",
+            backgroundColor: "#1e1e1e",
+            borderRadius:
+              showLanguageBadge || showCopyButton
+                ? "0 0 0.5rem 0.5rem"
+                : "0.5rem",
+            padding: "1rem",
+          }}
+        >
+          <SyntaxHighlighter
+            PreTag="div"
+            language={language}
+            style={dark}
+            customStyle={{
+              backgroundColor: "transparent",
+              borderRadius: 0,
+              padding: 0,
+              margin: 0,
+              whiteSpace: "pre",
+              minWidth: "100%",
+            }}
+          >
+            {code}
+          </SyntaxHighlighter>
+        </div>
+      </Box>
+    );
+  },
+  (prev, next) =>
+    prev.language === next.language &&
+    prev.code === next.code &&
+    prev.showCopyButton === next.showCopyButton &&
+    prev.maxHeight === next.maxHeight,
+);
+
+CodeBlock.displayName = "CodeBlock";