@almadar/cli 0.3.2 → 1.0.3

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

@@ -0,0 +1,163 @@
+/**
+ * FlashCardStack - Manages a stack of flashcards with navigation and progress
+ *
+ * Almadar Entity Binding:
+ * - Data flows through `cards` prop from Almadar state
+ * - User interactions emit events via useEventBus()
+ *
+ * Events Emitted:
+ * - UI:CARD_CHANGED - When active card changes
+ * - UI:STACK_COMPLETED - When all cards have been studied
+ * - UI:SHUFFLE_CARDS - When shuffle is requested
+ * - UI:RESET_STACK - When stack reset is requested
+ */
+
+import React, { useState, useCallback } from "react";
+import { Shuffle, RotateCcw, CheckCircle } from "lucide-react";
+import { Box } from "../../../components/atoms/Box";
+import { VStack } from "../../../components/atoms/Stack";
+import { HStack } from "../../../components/atoms/Stack";
+import { Card } from "../../../components/molecules/Card";
+import { FlashCard, FlashCardEntity } from "./FlashCard";
+import { useEventBus } from "../../../hooks/useEventBus";
+
+export interface FlashCardStackProps {
+  /** Array of flashcard entities */
+  cards: FlashCardEntity[];
+  /** Current card index (controlled) */
+  currentIndex?: number;
+  /** Show shuffle button */
+  showShuffle?: boolean;
+  /** Show completion summary */
+  showSummary?: boolean;
+  /** Additional CSS classes */
+  className?: string;
+}
+
+export const FlashCardStack: React.FC<FlashCardStackProps> = ({
+  cards,
+  currentIndex: controlledIndex,
+  showShuffle = true,
+  showSummary = true,
+  className = "",
+}) => {
+  const { emit } = useEventBus();
+  const [internalIndex, setInternalIndex] = useState(0);
+  const currentIndex =
+    controlledIndex !== undefined ? controlledIndex : internalIndex;
+
+  const studiedCount = cards.filter((c) => c.studied).length;
+  const isComplete = studiedCount === cards.length && cards.length > 0;
+
+  const goToCard = useCallback(
+    (index: number) => {
+      const clampedIndex = Math.max(0, Math.min(index, cards.length - 1));
+      if (controlledIndex === undefined) {
+        setInternalIndex(clampedIndex);
+      }
+      emit("UI:CARD_CHANGED", {
+        cardIndex: clampedIndex,
+        cardId: cards[clampedIndex]?.id,
+      });
+    },
+    [cards, controlledIndex, emit],
+  );
+
+  const handleShuffle = () => {
+    emit("UI:SHUFFLE_CARDS", { cardIds: cards.map((c) => c.id) });
+  };
+
+  const handleReset = () => {
+    if (controlledIndex === undefined) {
+      setInternalIndex(0);
+    }
+    emit("UI:RESET_STACK", { cardIds: cards.map((c) => c.id) });
+  };
+
+  if (cards.length === 0) {
+    return (
+      <Card className={`border border-gray-200 ${className}`}>
+        <VStack gap="sm" align="center" className="py-8 text-gray-500">
+          <span className="text-lg">No flashcards available</span>
+          <span className="text-sm">Add some cards to start studying</span>
+        </VStack>
+      </Card>
+    );
+  }
+
+  if (isComplete && showSummary) {
+    return (
+      <Card className={`shadow-md ${className} bg-green-50 border-green-200`}>
+        <VStack gap="md" align="center" className="py-8">
+          <CheckCircle size={48} className="text-green-500" />
+          <span className="text-xl font-semibold text-green-700">
+            All cards studied!
+          </span>
+          <span className="text-sm text-green-600">
+            You've completed all {cards.length} flashcards
+          </span>
+          <button
+            className="mt-4 px-4 py-2 text-sm font-medium bg-green-600 text-white rounded hover:bg-green-700 flex items-center gap-2"
+            onClick={handleReset}
+          >
+            <RotateCcw size={16} />
+            Study Again
+          </button>
+        </VStack>
+      </Card>
+    );
+  }
+
+  const currentCard = cards[currentIndex];
+
+  return (
+    <VStack gap="md" className={`w-full max-w-md mx-auto ${className}`}>
+      {/* Stack Controls */}
+      <HStack justify="between" align="center">
+        <span className="text-sm text-gray-500">
+          {studiedCount} of {cards.length} studied
+        </span>
+        {showShuffle && (
+          <button
+            className="p-2 text-gray-500 hover:text-gray-700 hover:bg-gray-100 rounded"
+            onClick={handleShuffle}
+            title="Shuffle cards"
+          >
+            <Shuffle size={18} />
+          </button>
+        )}
+      </HStack>
+
+      {/* Progress dots */}
+      <HStack gap="xs" justify="center" wrap>
+        {cards.map((card, idx) => (
+          <button
+            key={card.id}
+            className={`w-3 h-3 rounded-full transition-all ${
+              idx === currentIndex
+                ? "bg-indigo-600 scale-125"
+                : card.studied
+                  ? "bg-green-500"
+                  : "bg-gray-300 hover:bg-gray-400"
+            }`}
+            onClick={() => goToCard(idx)}
+            title={`Card ${idx + 1}${card.studied ? " (studied)" : ""}`}
+          />
+        ))}
+      </HStack>
+
+      {/* Current Card */}
+      {currentCard && (
+        <FlashCard
+          entity={currentCard}
+          currentCard={currentIndex + 1}
+          totalCards={cards.length}
+          showNavigation={true}
+          showActions={true}
+        />
+      )}
+    </VStack>
+  );
+};
+
+FlashCardStack.displayName = "FlashCardStack";

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

@@ -0,0 +1,236 @@
+import React, { useState, useEffect } from 'react';
+import { FlashCard } from '../types';
+import { RotateCcw, Edit2, X, Check, Plus, Trash2 } from 'lucide-react';
+
+interface FlashCardsDisplayProps {
+  flashCards: FlashCard[];
+  isEditing?: boolean;
+  onEdit?: () => void;
+  onCancelEdit?: () => void;
+  onSaveFlashCards?: (flashCards: Array<{ front: string; back: string }>) => void;
+}
+
+const FlashCardsDisplay: React.FC<FlashCardsDisplayProps> = ({ 
+  flashCards,
+  isEditing = false,
+  onEdit,
+  onCancelEdit,
+  onSaveFlashCards,
+}) => {
+  const [isFlipped, setIsFlipped] = useState<Record<number, boolean>>({});
+  const [editCards, setEditCards] = useState<Array<{ front: string; back: string }>>([]);
+
+  useEffect(() => {
+    if (flashCards.length > 0) {
+      setEditCards(flashCards.map(card => ({ front: card.front, back: card.back })));
+    } else if (isEditing && flashCards.length === 0) {
+      // When entering edit mode with no existing cards, initialize with one empty card
+      setEditCards([{ front: '', back: '' }]);
+    }
+  }, [flashCards, isEditing]);
+
+  const handleSave = () => {
+    if (onSaveFlashCards) {
+      onSaveFlashCards(editCards.filter(card => card.front.trim() && card.back.trim()));
+    }
+  };
+
+  const handleCancel = () => {
+    setEditCards(flashCards.map(card => ({ front: card.front, back: card.back })));
+    if (onCancelEdit) {
+      onCancelEdit();
+    }
+  };
+
+  const handleAddCard = () => {
+    setEditCards([...editCards, { front: '', back: '' }]);
+  };
+
+  const handleRemoveCard = (index: number) => {
+    setEditCards(editCards.filter((_, i) => i !== index));
+  };
+
+  const handleCardChange = (index: number, field: 'front' | 'back', value: string) => {
+    const updated = [...editCards];
+    updated[index] = { ...updated[index], [field]: value };
+    setEditCards(updated);
+  };
+
+  const handleFlip = (index: number) => {
+    setIsFlipped(prev => ({
+      ...prev,
+      [index]: !prev[index],
+    }));
+  };
+
+  const handleReset = () => {
+    setIsFlipped({});
+  };
+
+  if (flashCards.length === 0 && !isEditing) {
+    return null;
+  }
+
+  return (
+    <div className="mt-8">
+      <div className="flex items-center justify-between mb-4">
+        <h3 className="text-xl font-semibold text-gray-900 dark:text-gray-100">
+          Flash Cards
+        </h3>
+        <div className="flex items-center gap-2">
+          {isEditing ? (
+            <>
+              <button
+                onClick={handleSave}
+                className="inline-flex items-center gap-1 px-3 py-1.5 bg-green-600 text-white rounded-lg hover:bg-green-700 text-sm"
+              >
+                <Check size={16} />
+                Save
+              </button>
+              <button
+                onClick={handleCancel}
+                className="inline-flex items-center gap-1 px-3 py-1.5 bg-gray-500 text-white rounded-lg hover:bg-gray-600 text-sm"
+              >
+                <X size={16} />
+                Cancel
+              </button>
+            </>
+          ) : (
+            <>
+              {onEdit && (
+                <button
+                  onClick={onEdit}
+                  className="inline-flex items-center gap-1 px-3 py-1.5 text-sm text-gray-600 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-100 border border-gray-300 dark:border-gray-600 rounded-lg hover:bg-gray-50 dark:hover:bg-gray-700"
+                >
+                  <Edit2 size={14} />
+                  Edit
+                </button>
+              )}
+              <button
+                onClick={handleReset}
+                className="text-sm text-gray-600 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-100 flex items-center gap-1"
+              >
+                <RotateCcw size={14} />
+                Reset All
+              </button>
+            </>
+          )}
+        </div>
+      </div>
+
+      {/* Horizontal scrollable container */}
+      <div className="relative">
+        <div className="flex gap-4 overflow-x-auto pb-4 scrollbar-thin scrollbar-thumb-gray-300 dark:scrollbar-thumb-gray-600 scrollbar-track-transparent">
+          {isEditing ? (
+            <>
+              {editCards.map((card, index) => (
+                <div
+                  key={index}
+                  className="flex-shrink-0 w-80"
+                >
+                  <div className="bg-white dark:bg-gray-800 border border-gray-300 dark:border-gray-600 rounded-lg p-4 shadow-lg">
+                    <div className="flex items-center justify-between mb-3">
+                      <span className="text-sm font-medium text-gray-700 dark:text-gray-300">Card {index + 1}</span>
+                      <button
+                        onClick={() => handleRemoveCard(index)}
+                        className="text-red-500 hover:text-red-700 dark:text-red-400 dark:hover:text-red-300"
+                      >
+                        <Trash2 size={16} />
+                      </button>
+                    </div>
+                    <div className="space-y-3">
+                      <div>
+                        <label className="block text-xs font-medium text-gray-600 dark:text-gray-400 mb-1">Question</label>
+                        <textarea
+                          value={card.front}
+                          onChange={(e) => handleCardChange(index, 'front', e.target.value)}
+                          className="w-full p-2 border border-gray-300 dark:border-gray-600 rounded bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 text-sm resize-none"
+                          rows={3}
+                          placeholder="Enter question..."
+                        />
+                      </div>
+                      <div>
+                        <label className="block text-xs font-medium text-gray-600 dark:text-gray-400 mb-1">Answer</label>
+                        <textarea
+                          value={card.back}
+                          onChange={(e) => handleCardChange(index, 'back', e.target.value)}
+                          className="w-full p-2 border border-gray-300 dark:border-gray-600 rounded bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100 text-sm resize-none"
+                          rows={3}
+                          placeholder="Enter answer..."
+                        />
+                      </div>
+                    </div>
+                  </div>
+                </div>
+              ))}
+              <div className="flex-shrink-0 w-80">
+                <button
+                  onClick={handleAddCard}
+                  className="w-full h-64 border-2 border-dashed border-gray-300 dark:border-gray-600 rounded-lg flex flex-col items-center justify-center text-gray-500 dark:text-gray-400 hover:border-gray-400 dark:hover:border-gray-500 hover:text-gray-600 dark:hover:text-gray-300 transition-colors"
+                >
+                  <Plus size={32} />
+                  <span className="mt-2 text-sm">Add Card</span>
+                </button>
+              </div>
+            </>
+          ) : (
+            flashCards.map((card, index) => {
+              const flipped = isFlipped[index] || false;
+              return (
+                <div
+                  key={index}
+                  className="flex-shrink-0 w-80 h-64"
+                  style={{ perspective: '1000px' }}
+                >
+                  <div
+                    className="relative w-full h-full transition-transform duration-500"
+                    style={{
+                      transformStyle: 'preserve-3d',
+                      transform: flipped ? 'rotateY(180deg)' : 'rotateY(0deg)',
+                    }}
+                    onClick={() => handleFlip(index)}
+                  >
+                    {/* Front of card */}
+                    <div
+                      className="absolute inset-0 w-full h-full rounded-lg shadow-lg cursor-pointer"
+                      style={{
+                        backfaceVisibility: 'hidden',
+                        transform: 'rotateY(0deg)',
+                      }}
+                    >
+                      <div className="bg-gradient-to-br from-indigo-500 to-purple-600 text-white rounded-lg w-full h-full flex flex-col justify-center items-center p-6">
+                        <div className="text-sm text-indigo-100 mb-2 font-medium">Question</div>
+                        <p className="text-lg font-medium text-center">{card.front}</p>
+                      </div>
+                    </div>
+
+                    {/* Back of card */}
+                    <div
+                      className="absolute inset-0 w-full h-full rounded-lg shadow-lg cursor-pointer"
+                      style={{
+                        backfaceVisibility: 'hidden',
+                        transform: 'rotateY(180deg)',
+                      }}
+                    >
+                      <div className="bg-gradient-to-br from-purple-500 to-pink-600 text-white rounded-lg w-full h-full flex flex-col justify-center items-center p-6">
+                        <div className="text-sm text-purple-100 mb-2 font-medium">Answer</div>
+                        <p className="text-base text-center leading-relaxed">{card.back}</p>
+                      </div>
+                    </div>
+                  </div>
+                </div>
+              );
+            })
+          )}
+        </div>
+      </div>
+
+      <p className="text-xs text-gray-500 dark:text-gray-400 mt-2 text-center">
+        Click on a card to flip it • {flashCards.length} card{flashCards.length !== 1 ? 's' : ''}
+      </p>
+    </div>
+  );
+};
+
+export default FlashCardsDisplay;
+

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

@@ -0,0 +1,230 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { action } from "@storybook/addon-actions";
+import { ForceDirectedGraph, KnowledgeGraph } from "./ForceDirectedGraph";
+
+const meta: Meta<typeof ForceDirectedGraph> = {
+  title: "KFlow/Organisms/ForceDirectedGraph",
+  component: ForceDirectedGraph,
+  parameters: {
+    layout: "fullscreen",
+  },
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <div style={{ height: "600px", width: "100%" }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof ForceDirectedGraph>;
+
+// Mock knowledge graph data
+const mockGraph: KnowledgeGraph = {
+  seedConceptId: "concept-1",
+  nodes: {
+    "concept-1": {
+      id: "concept-1",
+      type: "Concept",
+      properties: {
+        name: "Photosynthesis",
+        description: "The process by which plants convert light energy into chemical energy",
+        layer: 0,
+        isSeed: true,
+      },
+    },
+    "concept-2": {
+      id: "concept-2",
+      type: "Concept",
+      properties: {
+        name: "Chlorophyll",
+        description: "Green pigment that absorbs light",
+        layer: 1,
+      },
+    },
+    "concept-3": {
+      id: "concept-3",
+      type: "Concept",
+      properties: {
+        name: "Light Reactions",
+        description: "First stage of photosynthesis",
+        layer: 1,
+      },
+    },
+    "concept-4": {
+      id: "concept-4",
+      type: "Concept",
+      properties: {
+        name: "Calvin Cycle",
+        description: "Second stage of photosynthesis",
+        layer: 1,
+      },
+    },
+    "concept-5": {
+      id: "concept-5",
+      type: "Concept",
+      properties: {
+        name: "ATP",
+        description: "Energy currency of cells",
+        layer: 2,
+      },
+    },
+    "concept-6": {
+      id: "concept-6",
+      type: "Concept",
+      properties: {
+        name: "NADPH",
+        description: "Electron carrier",
+        layer: 2,
+      },
+    },
+    "layer-1": {
+      id: "layer-1",
+      type: "Layer",
+      properties: {
+        name: "Layer 1",
+        layer: 1,
+      },
+    },
+    "layer-2": {
+      id: "layer-2",
+      type: "Layer",
+      properties: {
+        name: "Layer 2",
+        layer: 2,
+      },
+    },
+    "goal-1": {
+      id: "goal-1",
+      type: "LearningGoal",
+      properties: {
+        name: "Understand Photosynthesis",
+      },
+    },
+    "lesson-1": {
+      id: "lesson-1",
+      type: "Lesson",
+      properties: {
+        name: "Introduction to Photosynthesis",
+      },
+    },
+  },
+  relationships: [
+    { source: "concept-1", target: "concept-2", type: "hasChild" },
+    { source: "concept-1", target: "concept-3", type: "hasChild" },
+    { source: "concept-1", target: "concept-4", type: "hasChild" },
+    { source: "concept-3", target: "concept-5", type: "hasChild" },
+    { source: "concept-3", target: "concept-6", type: "hasChild" },
+    { source: "concept-4", target: "concept-5", type: "hasPrerequisite" },
+    { source: "concept-2", target: "layer-1", type: "belongsToLayer" },
+    { source: "concept-3", target: "layer-1", type: "belongsToLayer" },
+    { source: "concept-4", target: "layer-1", type: "belongsToLayer" },
+    { source: "concept-5", target: "layer-2", type: "belongsToLayer" },
+    { source: "concept-6", target: "layer-2", type: "belongsToLayer" },
+    { source: "concept-1", target: "goal-1", type: "hasLearningGoal" },
+    { source: "concept-1", target: "lesson-1", type: "hasLesson" },
+  ],
+};
+
+// Smaller graph for simple example
+const simpleGraph: KnowledgeGraph = {
+  seedConceptId: "node-1",
+  nodes: {
+    "node-1": {
+      id: "node-1",
+      type: "Concept",
+      properties: { name: "Main Concept", isSeed: true },
+    },
+    "node-2": {
+      id: "node-2",
+      type: "Concept",
+      properties: { name: "Child A", layer: 1 },
+    },
+    "node-3": {
+      id: "node-3",
+      type: "Concept",
+      properties: { name: "Child B", layer: 1 },
+    },
+    "node-4": {
+      id: "node-4",
+      type: "Concept",
+      properties: { name: "Child C", layer: 1 },
+    },
+  },
+  relationships: [
+    { source: "node-1", target: "node-2", type: "hasChild" },
+    { source: "node-1", target: "node-3", type: "hasChild" },
+    { source: "node-1", target: "node-4", type: "hasChild" },
+    { source: "node-2", target: "node-3", type: "hasPrerequisite" },
+  ],
+};
+
+export const Default: Story = {
+  args: {
+    graph: mockGraph,
+    showLabels: true,
+    showLegend: true,
+    onNodeClick: action("UI:SELECT_NODE"),
+  },
+};
+
+export const SimpleGraph: Story = {
+  args: {
+    graph: simpleGraph,
+    showLabels: true,
+    showLegend: true,
+    onNodeClick: action("UI:SELECT_NODE"),
+  },
+};
+
+export const NoLegend: Story = {
+  args: {
+    graph: mockGraph,
+    showLabels: true,
+    showLegend: false,
+    onNodeClick: action("UI:SELECT_NODE"),
+  },
+};
+
+export const NoLabels: Story = {
+  args: {
+    graph: mockGraph,
+    showLabels: false,
+    showLegend: true,
+    onNodeClick: action("UI:SELECT_NODE"),
+  },
+};
+
+export const Loading: Story = {
+  args: {
+    graph: null,
+    isLoading: true,
+  },
+};
+
+export const Empty: Story = {
+  args: {
+    graph: null,
+    isLoading: false,
+  },
+};
+
+export const FixedDimensions: Story = {
+  args: {
+    graph: simpleGraph,
+    width: 600,
+    height: 400,
+    showLabels: true,
+    showLegend: false,
+    onNodeClick: action("UI:SELECT_NODE"),
+  },
+  decorators: [
+    (Story) => (
+      <div style={{ padding: "20px", backgroundColor: "#f5f5f5" }}>
+        <Story />
+      </div>
+    ),
+  ],
+};