@almadar/cli 0.3.2 → 1.0.3

package/shells/typescript-shell/packages/client/src/clients/kflow/patterns/component-mapping.json

@@ -0,0 +1,122 @@
+{
+  "version": "1.0.0",
+  "client": "kflow",
+  "description": "KFlow client-specific pattern to component mappings",
+  "mappings": {
+    "concept-card": {
+      "component": "ConceptCard",
+      "importPath": "@kflow/design-system/organisms/ConceptCard",
+      "category": "learning"
+    },
+    "flashcard": {
+      "component": "FlashCard",
+      "importPath": "@kflow/design-system/organisms/FlashCard",
+      "category": "learning"
+    },
+    "flashcard-stack": {
+      "component": "FlashCardStack",
+      "importPath": "@kflow/design-system/organisms/FlashCardStack",
+      "category": "learning"
+    },
+    "force-graph": {
+      "component": "ForceDirectedGraph",
+      "importPath": "@kflow/design-system/organisms/ForceDirectedGraph",
+      "category": "visualization"
+    },
+    "knowledge-graph": {
+      "component": "ForceDirectedGraph",
+      "importPath": "@kflow/design-system/organisms/ForceDirectedGraph",
+      "category": "visualization"
+    },
+    "graph-legend": {
+      "component": "GraphLegend",
+      "importPath": "@kflow/design-system/molecules/GraphLegend",
+      "category": "visualization"
+    },
+    "mindmap-canvas": {
+      "component": "MindMapCanvas",
+      "importPath": "@kflow/design-system/organisms/MindMapCanvas",
+      "category": "visualization"
+    },
+    "mindmap-node": {
+      "component": "MindMapNode",
+      "importPath": "@kflow/design-system/molecules/MindMapNode",
+      "category": "visualization"
+    },
+    "segment-renderer": {
+      "component": "SegmentRenderer",
+      "importPath": "@kflow/design-system/organisms/SegmentRenderer",
+      "category": "learning"
+    },
+    "lesson-content": {
+      "component": "SegmentRenderer",
+      "importPath": "@kflow/design-system/organisms/SegmentRenderer",
+      "category": "learning"
+    },
+    "activation-block": {
+      "component": "ActivationBlock",
+      "importPath": "@kflow/design-system/molecules/learning/ActivationBlock",
+      "category": "learning-science"
+    },
+    "reflection-block": {
+      "component": "ReflectionBlock",
+      "importPath": "@kflow/design-system/molecules/learning/ReflectionBlock",
+      "category": "learning-science"
+    },
+    "connection-block": {
+      "component": "ConnectionBlock",
+      "importPath": "@kflow/design-system/molecules/learning/ConnectionBlock",
+      "category": "learning-science"
+    },
+    "bloom-quiz": {
+      "component": "BloomQuizBlock",
+      "importPath": "@kflow/design-system/molecules/learning/BloomQuizBlock",
+      "category": "learning-science"
+    },
+    "code-block": {
+      "component": "CodeBlock",
+      "importPath": "@kflow/design-system/molecules/markdown/CodeBlock",
+      "category": "content"
+    },
+    "markdown-content": {
+      "component": "MarkdownContent",
+      "importPath": "@kflow/design-system/molecules/markdown/MarkdownContent",
+      "category": "content"
+    },
+    "note-list": {
+      "component": "NoteList",
+      "importPath": "@kflow/design-system/organisms/NoteList",
+      "category": "notes"
+    },
+    "note-item": {
+      "component": "NoteListItem",
+      "importPath": "@kflow/design-system/molecules/NoteListItem",
+      "category": "notes"
+    },
+    "note-content": {
+      "component": "NoteContent",
+      "importPath": "@kflow/design-system/molecules/NoteContent",
+      "category": "notes"
+    },
+    "layer-navigator": {
+      "component": "LayerNavigator",
+      "importPath": "@kflow/design-system/molecules/LayerNavigator",
+      "category": "navigation"
+    },
+    "learning-goal": {
+      "component": "LearningGoalDisplay",
+      "importPath": "@kflow/design-system/molecules/LearningGoalDisplay",
+      "category": "learning"
+    },
+    "concept-meta-tags": {
+      "component": "ConceptMetaTags",
+      "importPath": "@kflow/design-system/molecules/ConceptMetaTags",
+      "category": "learning"
+    },
+    "streaming-display": {
+      "component": "StreamingDisplay",
+      "importPath": "@kflow/design-system/molecules/StreamingDisplay",
+      "category": "content"
+    }
+  }
+}

package/shells/typescript-shell/packages/client/src/clients/kflow/patterns/event-contracts.json

@@ -0,0 +1,145 @@
+{
+  "version": "1.0.0",
+  "client": "kflow",
+  "description": "KFlow client-specific event contracts",
+  "contracts": {
+    "concept-card": {
+      "emits": [
+        { "event": "UI:SELECT_CONCEPT", "trigger": "click", "payload": { "conceptId": "string", "entity": "object" } },
+        { "event": "UI:EXPAND_CONCEPT", "trigger": "click", "payload": { "conceptId": "string", "expanded": "boolean" } },
+        { "event": "UI:CONCEPT_ACTION", "trigger": "click", "payload": { "conceptId": "string", "action": "string" } }
+      ]
+    },
+    "flashcard": {
+      "emits": [
+        { "event": "UI:FLIP_CARD", "trigger": "click", "payload": { "cardId": "string", "flipped": "boolean" } },
+        { "event": "UI:MARK_STUDIED", "trigger": "click", "payload": { "cardId": "string" } },
+        { "event": "UI:RESET_CARD", "trigger": "click", "payload": { "cardId": "string" } },
+        { "event": "UI:NEXT_CARD", "trigger": "click", "payload": { "currentCardId": "string" } },
+        { "event": "UI:PREV_CARD", "trigger": "click", "payload": { "currentCardId": "string" } }
+      ]
+    },
+    "flashcard-stack": {
+      "emits": [
+        { "event": "UI:CARD_CHANGED", "trigger": "navigation", "payload": { "cardIndex": "number", "cardId": "string" } },
+        { "event": "UI:STACK_COMPLETED", "trigger": "complete", "payload": { "cardIds": "array" } },
+        { "event": "UI:SHUFFLE_CARDS", "trigger": "click", "payload": { "cardIds": "array" } },
+        { "event": "UI:RESET_STACK", "trigger": "click", "payload": { "cardIds": "array" } }
+      ]
+    },
+    "force-graph": {
+      "emits": [
+        { "event": "UI:SELECT_NODE", "trigger": "click", "payload": { "nodeId": "string", "node": "object" } },
+        { "event": "UI:HOVER_NODE", "trigger": "hover", "payload": { "nodeId": "string", "node": "object" } }
+      ]
+    },
+    "graph-legend": {
+      "emits": [
+        { "event": "UI:TOGGLE_LEGEND_ITEM", "trigger": "click", "payload": { "itemId": "string", "visible": "boolean" } }
+      ]
+    },
+    "mindmap-canvas": {
+      "emits": [
+        { "event": "UI:MINDMAP_PAN", "trigger": "drag", "payload": { "offset": "object" } },
+        { "event": "UI:MINDMAP_ZOOM", "trigger": "wheel", "payload": { "scale": "number" } },
+        { "event": "UI:MINDMAP_FOCUS", "trigger": "focus", "payload": {} },
+        { "event": "UI:MINDMAP_BLUR", "trigger": "blur", "payload": {} }
+      ]
+    },
+    "mindmap-node": {
+      "emits": [
+        { "event": "UI:SELECT_NODE", "trigger": "click", "payload": { "nodeId": "string" } },
+        { "event": "UI:EDIT_NODE", "trigger": "dblclick", "payload": { "nodeId": "string" } },
+        { "event": "UI:EXPAND_NODE", "trigger": "click", "payload": { "nodeId": "string", "expanded": "boolean" } },
+        { "event": "UI:AI_GENERATE", "trigger": "click", "payload": { "nodeId": "string" } }
+      ]
+    },
+    "activation-block": {
+      "emits": [
+        { "event": "UI:SAVE_ACTIVATION", "trigger": "click", "payload": { "response": "string", "conceptId": "string" } },
+        { "event": "UI:SKIP_ACTIVATION", "trigger": "click", "payload": { "conceptId": "string" } }
+      ]
+    },
+    "reflection-block": {
+      "emits": [
+        { "event": "UI:SAVE_REFLECTION", "trigger": "click", "payload": { "reflection": "string", "sectionId": "string" } }
+      ]
+    },
+    "bloom-quiz": {
+      "emits": [
+        { "event": "UI:ANSWER_BLOOM", "trigger": "click", "payload": { "questionId": "string", "selectedIndex": "number", "isCorrect": "boolean" } },
+        { "event": "UI:REVEAL_ANSWER", "trigger": "click", "payload": { "questionId": "string" } }
+      ]
+    },
+    "code-block": {
+      "emits": [
+        { "event": "UI:COPY_CODE", "trigger": "click", "payload": { "code": "string", "language": "string" } }
+      ]
+    },
+    "note-list": {
+      "emits": [
+        { "event": "UI:ADD_NOTE", "trigger": "click", "payload": {} }
+      ]
+    },
+    "note-item": {
+      "emits": [
+        { "event": "UI:SELECT_NOTE", "trigger": "click", "payload": { "noteId": "string" } },
+        { "event": "UI:DELETE_NOTE", "trigger": "click", "payload": { "noteId": "string" } },
+        { "event": "UI:EDIT_NOTE", "trigger": "click", "payload": { "noteId": "string", "newTitle": "string" } },
+        { "event": "UI:EXPAND_NOTE", "trigger": "click", "payload": { "noteId": "string", "expanded": "boolean" } },
+        { "event": "UI:ADD_CHILD_NOTE", "trigger": "click", "payload": { "parentId": "string" } }
+      ]
+    },
+    "note-content": {
+      "emits": [
+        { "event": "UI:EDIT_NOTE_CONTENT", "trigger": "click", "payload": { "noteId": "string" } },
+        { "event": "UI:SAVE_NOTE_CONTENT", "trigger": "blur", "payload": { "noteId": "string", "content": "string" } }
+      ]
+    },
+    "layer-navigator": {
+      "emits": [
+        { "event": "UI:SELECT_LAYER", "trigger": "click", "payload": { "layerNumber": "number" } },
+        { "event": "UI:PREV_LAYER", "trigger": "click", "payload": { "layerNumber": "number" } },
+        { "event": "UI:NEXT_LAYER", "trigger": "click", "payload": { "layerNumber": "number" } }
+      ]
+    },
+    "learning-goal": {
+      "emits": [
+        { "event": "UI:EDIT_GOAL", "trigger": "click", "payload": { "layerNumber": "number", "graphId": "string" } },
+        { "event": "UI:SAVE_GOAL", "trigger": "click", "payload": { "layerNumber": "number", "graphId": "string", "goal": "string" } },
+        { "event": "UI:CANCEL_EDIT_GOAL", "trigger": "click", "payload": { "layerNumber": "number", "graphId": "string" } }
+      ]
+    },
+    "concept-meta-tags": {
+      "emits": [
+        { "event": "UI:NAVIGATE_TO_PARENT", "trigger": "click", "payload": { "parentName": "string" } }
+      ]
+    },
+    "lesson-template": {
+      "emits": [
+        { "event": "UI:LESSON_COMPLETE", "trigger": "click", "payload": { "lessonId": "string" } },
+        { "event": "UI:LESSON_NEXT", "trigger": "click", "payload": { "currentLessonId": "string" } },
+        { "event": "UI:LESSON_PREV", "trigger": "click", "payload": { "currentLessonId": "string" } },
+        { "event": "UI:TOGGLE_SIDEBAR", "trigger": "click", "payload": { "open": "boolean" } },
+        { "event": "UI:SELECT_LESSON", "trigger": "click", "payload": { "lessonId": "string" } }
+      ]
+    },
+    "concept-detail-template": {
+      "emits": [
+        { "event": "UI:START_LESSON", "trigger": "click", "payload": { "conceptId": "string" } },
+        { "event": "UI:START_PRACTICE", "trigger": "click", "payload": { "conceptId": "string" } },
+        { "event": "UI:NAVIGATE_PREREQUISITE", "trigger": "click", "payload": { "prerequisiteName": "string", "fromConcept": "string" } },
+        { "event": "UI:BACK", "trigger": "click", "payload": { "fromConcept": "string" } },
+        { "event": "UI:GENERATE_LESSON", "trigger": "click", "payload": { "conceptId": "string" } }
+      ]
+    },
+    "knowledge-graph-template": {
+      "emits": [
+        { "event": "UI:SELECT_NODE", "trigger": "click", "payload": { "nodeId": "string", "graphId": "string" } },
+        { "event": "UI:SELECT_LAYER", "trigger": "click", "payload": { "layerNumber": "number" } },
+        { "event": "UI:TOGGLE_VIEW", "trigger": "click", "payload": { "mode": "string", "graphId": "string" } },
+        { "event": "UI:VIEW_CONCEPT", "trigger": "click", "payload": { "conceptId": "string" } }
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,46 @@
+/**
+ * KFlow Pattern Registry
+ *
+ * Client-specific pattern definitions for the KFlow educational platform.
+ * These extend the core almadar-shared patterns with learning-focused components.
+ */
+
+import componentMapping from './component-mapping.json';
+import eventContracts from './event-contracts.json';
+
+export { componentMapping, eventContracts };
+
+/**
+ * Get component mapping for a pattern type
+ */
+export function getKflowComponentMapping(patternType: string) {
+  return (componentMapping.mappings as Record<string, unknown>)[patternType];
+}
+
+/**
+ * Get event contract for a pattern type
+ */
+export function getKflowEventContract(patternType: string) {
+  return (eventContracts.contracts as Record<string, unknown>)[patternType];
+}
+
+/**
+ * List all KFlow-specific pattern types
+ */
+export function listKflowPatterns(): string[] {
+  return Object.keys(componentMapping.mappings);
+}
+
+/**
+ * Pattern categories specific to KFlow
+ */
+export const KFLOW_CATEGORIES = [
+  'learning',
+  'learning-science',
+  'visualization',
+  'content',
+  'notes',
+  'navigation',
+] as const;
+
+export type KflowCategory = (typeof KFLOW_CATEGORIES)[number];

package/shells/typescript-shell/packages/client/src/clients/kflow/templates/ConceptDetailTemplate.stories.tsx

@@ -0,0 +1,148 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { ConceptDetailTemplate } from './ConceptDetailTemplate';
+
+const meta: Meta<typeof ConceptDetailTemplate> = {
+  title: 'KFlow/Templates/ConceptDetailTemplate',
+  component: ConceptDetailTemplate,
+  parameters: {
+    layout: 'fullscreen',
+  },
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof ConceptDetailTemplate>;
+
+const sampleLessonSegments = [
+  {
+    type: 'markdown' as const,
+    content: `## Understanding Backpropagation
+
+Backpropagation is the fundamental algorithm used to train neural networks. It calculates the gradient of the loss function with respect to each weight by propagating the error backward through the network.
+
+### The Chain Rule
+
+The chain rule of calculus is essential to understanding backpropagation. It allows us to compute derivatives of composite functions.
+`,
+  },
+  {
+    type: 'code' as const,
+    content: `def backward(self, grad_output):
+    # Compute gradients
+    grad_weights = np.dot(self.input.T, grad_output)
+    grad_input = np.dot(grad_output, self.weights.T)
+
+    # Update weights
+    self.weights -= learning_rate * grad_weights
+
+    return grad_input`,
+    language: 'python',
+  },
+];
+
+const sampleFlashcards = [
+  { id: '1', front: 'What is backpropagation?', back: 'An algorithm for calculating gradients by propagating errors backward through a network.' },
+  { id: '2', front: 'What mathematical rule is essential to backpropagation?', back: 'The chain rule of calculus.' },
+  { id: '3', front: 'What do we update during backpropagation?', back: 'The weights of the neural network.' },
+];
+
+export const Default: Story = {
+  args: {
+    entity: {
+      id: 'concept-1',
+      name: 'Backpropagation',
+      description: 'The fundamental algorithm for training neural networks by computing gradients through the chain rule.',
+      layer: 2,
+      prerequisites: ['Gradient Descent', 'Chain Rule', 'Neural Network Basics'],
+      parents: ['Neural Networks', 'Optimization'],
+      learningGoal: 'Understand how backpropagation works and be able to implement it from scratch.',
+      hasLesson: true,
+      lessonSegments: sampleLessonSegments,
+      flashcards: sampleFlashcards,
+      progress: 45,
+    },
+    graphId: 'ml-course-1',
+  },
+};
+
+export const NoLesson: Story = {
+  args: {
+    entity: {
+      id: 'concept-2',
+      name: 'Transformer Architecture',
+      description: 'The architecture behind modern language models like GPT and BERT.',
+      layer: 4,
+      prerequisites: ['Attention Mechanism', 'Embeddings'],
+      parents: ['Deep Learning'],
+      hasLesson: false,
+      progress: 0,
+    },
+  },
+};
+
+export const SeedConcept: Story = {
+  args: {
+    entity: {
+      id: 'concept-3',
+      name: 'Mathematics Foundations',
+      description: 'Core mathematical concepts needed for machine learning.',
+      layer: 0,
+      isSeed: true,
+      learningGoal: 'Build a strong foundation in linear algebra, calculus, and probability.',
+      hasLesson: true,
+      lessonSegments: sampleLessonSegments,
+      progress: 100,
+    },
+  },
+};
+
+export const WithFlashcardsOnly: Story = {
+  args: {
+    entity: {
+      id: 'concept-4',
+      name: 'Activation Functions',
+      description: 'Non-linear functions used in neural networks.',
+      layer: 1,
+      flashcards: [
+        { id: '1', front: 'What is ReLU?', back: 'Rectified Linear Unit: f(x) = max(0, x)' },
+        { id: '2', front: 'What is Sigmoid?', back: 'f(x) = 1 / (1 + e^(-x))' },
+        { id: '3', front: 'What is Tanh?', back: 'Hyperbolic tangent: f(x) = (e^x - e^(-x)) / (e^x + e^(-x))' },
+        { id: '4', front: 'Why use activation functions?', back: 'To introduce non-linearity, enabling the network to learn complex patterns.' },
+      ],
+      hasLesson: false,
+      progress: 25,
+    },
+  },
+};
+
+export const FullyCompleted: Story = {
+  args: {
+    entity: {
+      id: 'concept-5',
+      name: 'Linear Regression',
+      description: 'The simplest form of supervised learning.',
+      layer: 1,
+      prerequisites: ['Statistics Basics'],
+      parents: ['Machine Learning'],
+      learningGoal: 'Master linear regression and understand its assumptions.',
+      hasLesson: true,
+      lessonSegments: sampleLessonSegments,
+      flashcards: sampleFlashcards.map((c) => ({ ...c, studied: true })),
+      progress: 100,
+    },
+  },
+};
+
+export const NoBackButton: Story = {
+  args: {
+    entity: {
+      id: 'concept-6',
+      name: 'Introduction',
+      description: 'Welcome to the course.',
+      layer: 0,
+      hasLesson: true,
+      lessonSegments: sampleLessonSegments,
+    },
+    showBack: false,
+  },
+};