@almadar/cli 0.3.2 → 1.0.3

package/shells/typescript-shell/packages/client/src/clients/kflow/atoms/MindMapConnections.stories.tsx

@@ -0,0 +1,82 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { MindMapConnections, MindMapConnection } from "./MindMapConnections";
+
+const meta: Meta<typeof MindMapConnections> = {
+  title: "KFlow/Atoms/MindMapConnections",
+  component: MindMapConnections,
+  parameters: {
+    layout: "centered",
+  },
+  tags: ["autodocs"],
+  decorators: [
+    (Story) => (
+      <svg width="400" height="300" style={{ border: "1px solid #e5e7eb" }}>
+        <Story />
+      </svg>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof MindMapConnections>;
+
+const simpleConnections: MindMapConnection[] = [
+  { source: { x: 200, y: 50 }, target: { x: 100, y: 150 } },
+  { source: { x: 200, y: 50 }, target: { x: 300, y: 150 } },
+  { source: { x: 200, y: 50 }, target: { x: 200, y: 150 } },
+];
+
+const treeConnections: MindMapConnection[] = [
+  // Root to level 1
+  { source: { x: 200, y: 30 }, target: { x: 80, y: 100 } },
+  { source: { x: 200, y: 30 }, target: { x: 200, y: 100 } },
+  { source: { x: 200, y: 30 }, target: { x: 320, y: 100 } },
+  // Level 1 to level 2
+  { source: { x: 80, y: 100 }, target: { x: 40, y: 180 } },
+  { source: { x: 80, y: 100 }, target: { x: 120, y: 180 } },
+  { source: { x: 320, y: 100 }, target: { x: 280, y: 180 } },
+  { source: { x: 320, y: 100 }, target: { x: 360, y: 180 } },
+];
+
+export const Default: Story = {
+  args: {
+    connections: simpleConnections,
+    zoom: 1,
+    pan: { x: 0, y: 0 },
+  },
+};
+
+export const TreeStructure: Story = {
+  args: {
+    connections: treeConnections,
+    zoom: 1,
+    pan: { x: 0, y: 0 },
+  },
+};
+
+export const CustomColor: Story = {
+  args: {
+    connections: simpleConnections,
+    strokeColor: "#3b82f6",
+    strokeWidth: 3,
+  },
+};
+
+export const Zoomed: Story = {
+  args: {
+    connections: [
+      { source: { x: 100, y: 50 }, target: { x: 50, y: 100 } },
+      { source: { x: 100, y: 50 }, target: { x: 150, y: 100 } },
+    ],
+    zoom: 1.5,
+    pan: { x: 50, y: 25 },
+  },
+};
+
+export const WithPan: Story = {
+  args: {
+    connections: simpleConnections,
+    zoom: 1,
+    pan: { x: -50, y: 20 },
+  },
+};

package/shells/typescript-shell/packages/client/src/clients/kflow/atoms/MindMapConnections.tsx

@@ -0,0 +1,75 @@
+/**
+ * MindMapConnections Atom Component
+ *
+ * SVG lines connecting mindmap nodes.
+ *
+ * Event Contract:
+ * - No events emitted (display-only SVG element)
+ * - entityAware: false
+ */
+
+import React from "react";
+
+export interface MindMapConnection {
+  source: { x: number; y: number };
+  target: { x: number; y: number };
+  id?: string;
+}
+
+export interface MindMapConnectionsProps {
+  /** Array of connections to render */
+  connections: MindMapConnection[];
+  /** Current zoom level */
+  zoom?: number;
+  /** Current pan offset */
+  pan?: { x: number; y: number };
+  /** Line color */
+  strokeColor?: string;
+  /** Line width */
+  strokeWidth?: number;
+  /** Additional CSS classes */
+  className?: string;
+}
+
+export const MindMapConnections: React.FC<MindMapConnectionsProps> = ({
+  connections,
+  zoom = 1,
+  pan = { x: 0, y: 0 },
+  strokeColor = "#94a3b8",
+  strokeWidth = 2,
+  className,
+}) => {
+  return (
+    <g className={className}>
+      {connections.map((conn, index) => {
+        const sourceX = conn.source.x * zoom + pan.x;
+        const sourceY = conn.source.y * zoom + pan.y;
+        const targetX = conn.target.x * zoom + pan.x;
+        const targetY = conn.target.y * zoom + pan.y;
+
+        // Calculate control points for curved line
+        const midX = (sourceX + targetX) / 2;
+        const midY = (sourceY + targetY) / 2;
+        const dx = targetX - sourceX;
+        const dy = targetY - sourceY;
+        const curvature = 0.2;
+        const controlX = midX - dy * curvature;
+        const controlY = midY + dx * curvature;
+
+        return (
+          <path
+            key={conn.id || index}
+            d={`M ${sourceX} ${sourceY} Q ${controlX} ${controlY} ${targetX} ${targetY}`}
+            fill="none"
+            stroke={strokeColor}
+            strokeWidth={strokeWidth * zoom}
+            strokeLinecap="round"
+            className="mindmap-connection transition-all duration-200"
+          />
+        );
+      })}
+    </g>
+  );
+};
+
+MindMapConnections.displayName = "MindMapConnections";

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

@@ -0,0 +1,2 @@
+// Mindmap atoms
+export * from './MindMapConnections';

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

@@ -0,0 +1,96 @@
+/**
+ * KFlow Design System Components
+ *
+ * Educational/learning platform components built on the core design system.
+ * All components follow the Almadar Entity Binding pattern:
+ * - Data flows through entity/props from Almadar state
+ * - User interactions emit events via useEventBus()
+ */
+
+// Atoms - Basic building blocks
+export * from "./atoms";
+
+// Molecules - Composite components (excluding NODE_TYPE_COLORS to avoid conflict with organisms)
+export {
+  // Markdown components
+  CodeBlock,
+  type CodeBlockProps,
+  MarkdownContent,
+  type MarkdownContentProps,
+  // Learning components
+  ActivationBlock,
+  type ActivationBlockProps,
+  ReflectionBlock,
+  type ReflectionBlockProps,
+  // Mindmap components
+  MindMapNode,
+  type MindMapNodeProps,
+  // Notes components
+  NoteContent,
+  type NoteContentProps,
+  NoteListItem,
+  type NoteListItemProps,
+  // Graph components
+  GraphLegend,
+  type GraphLegendProps,
+  type LegendItem,
+  EDGE_TYPE_COLORS,
+  // Streaming components
+  StreamingDisplay,
+  type StreamingDisplayProps,
+  // Concept components
+  ConceptMetaTags,
+  type ConceptMetaTagsProps,
+  // Learning goal components
+  LearningGoalDisplay,
+  type LearningGoalDisplayProps,
+  // Layer navigation
+  LayerNavigator,
+  type LayerNavigatorProps,
+} from "./molecules";
+
+// Re-export NODE_TYPE_COLORS from molecules (canonical source)
+export { NODE_TYPE_COLORS } from "./molecules/GraphLegend";
+
+// Organisms - Complex feature components (excluding ConceptEntity to avoid conflict with templates)
+export {
+  // Learning content
+  SegmentRenderer,
+  type SegmentRendererProps,
+  // Graph visualization
+  ForceDirectedGraph,
+  type ForceDirectedGraphProps,
+  type GraphNode,
+  type GraphRelationship,
+  // Mindmap
+  MindMapCanvas,
+  type MindMapCanvasProps,
+  // Notes
+  NoteList,
+  type NoteListProps,
+  // Concept display
+  ConceptCard,
+  type ConceptCardProps,
+  // Flashcards
+  FlashCard,
+  type FlashCardProps,
+  type FlashCardEntity,
+  FlashCardStack,
+  type FlashCardStackProps,
+} from "./organisms";
+
+// Re-export ConceptEntity from organisms (canonical source)
+export { type ConceptEntity } from "./organisms/ConceptCard";
+
+// Utilities - Helper functions and types
+export * from "./utils";
+
+// Templates - Page-level layouts (excluding ConceptEntity to avoid conflict)
+export {
+  ConceptDetailTemplate,
+  type ConceptDetailTemplateProps,
+  KnowledgeGraphTemplate,
+  type KnowledgeGraphTemplateProps,
+  LessonTemplate,
+  type LessonTemplateProps,
+} from "./templates";

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

@@ -0,0 +1,64 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { ConceptMetaTags } from './ConceptMetaTags';
+
+const meta: Meta<typeof ConceptMetaTags> = {
+  title: 'KFlow/Molecules/ConceptMetaTags',
+  component: ConceptMetaTags,
+  parameters: {
+    layout: 'padded',
+  },
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof ConceptMetaTags>;
+
+export const Default: Story = {
+  args: {
+    layer: 2,
+    parents: ['Machine Learning', 'Statistics'],
+  },
+};
+
+export const WithLayerOnly: Story = {
+  args: {
+    layer: 3,
+    parents: [],
+  },
+};
+
+export const SeedConcept: Story = {
+  args: {
+    layer: 0,
+    isSeed: true,
+    parents: [],
+  },
+};
+
+export const SeedWithParents: Story = {
+  args: {
+    layer: 1,
+    isSeed: true,
+    parents: ['Mathematics'],
+  },
+};
+
+export const ManyParents: Story = {
+  args: {
+    layer: 4,
+    parents: ['Deep Learning', 'Neural Networks', 'Backpropagation', 'Optimization'],
+  },
+};
+
+export const ParentsOnly: Story = {
+  args: {
+    parents: ['Parent Concept 1', 'Parent Concept 2'],
+  },
+};
+
+export const HighLayer: Story = {
+  args: {
+    layer: 7,
+    parents: ['Advanced Topic'],
+  },
+};

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

@@ -0,0 +1,77 @@
+/**
+ * ConceptMetaTags - Displays concept metadata tags (layer, seed status, parents)
+ *
+ * Almadar Entity Binding:
+ * - Data flows through props from Almadar state
+ * - User interactions emit events via useEventBus()
+ *
+ * Events Emitted:
+ * - UI:NAVIGATE_TO_PARENT - When a parent concept is clicked
+ */
+
+import React from 'react';
+import { Layers } from 'lucide-react';
+import { HStack } from '../../../components/atoms/Stack';
+import { VStack } from '../../../components/atoms/Stack';
+import { useEventBus } from '../../../hooks/useEventBus';
+
+export interface ConceptMetaTagsProps {
+  /** Layer number */
+  layer?: number;
+  /** Whether this is a seed concept */
+  isSeed?: boolean;
+  /** Parent concept names */
+  parents: string[];
+  /** Additional CSS classes */
+  className?: string;
+}
+
+export const ConceptMetaTags: React.FC<ConceptMetaTagsProps> = ({
+  layer,
+  isSeed,
+  parents,
+  className = '',
+}) => {
+  const { emit } = useEventBus();
+
+  const handleParentClick = (parent: string) => {
+    emit('UI:NAVIGATE_TO_PARENT', { parentName: parent });
+  };
+
+  return (
+    <VStack gap="sm" className={className}>
+      {(layer !== undefined || isSeed) && (
+        <HStack gap="sm" wrap>
+          {layer !== undefined && (
+            <span className="inline-flex items-center gap-1 px-2 py-1 text-xs font-medium bg-blue-100 text-blue-700 rounded">
+              <Layers size={12} />
+              Level {layer}
+            </span>
+          )}
+          {isSeed && (
+            <span className="px-2 py-1 text-xs font-medium bg-amber-100 text-amber-700 rounded">
+              Seed Concept
+            </span>
+          )}
+        </HStack>
+      )}
+
+      {parents.length > 0 && (
+        <HStack gap="sm" wrap align="center">
+          <span className="text-sm text-gray-600 font-medium">Parents:</span>
+          {parents.map((parent) => (
+            <button
+              key={parent}
+              onClick={() => handleParentClick(parent)}
+              className="px-2 py-1 text-xs font-medium bg-purple-100 text-purple-700 rounded-full hover:bg-purple-200 transition-colors"
+            >
+              ← {parent}
+            </button>
+          ))}
+        </HStack>
+      )}
+    </VStack>
+  );
+};
+
+ConceptMetaTags.displayName = 'ConceptMetaTags';

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

@@ -0,0 +1,100 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { GraphLegend, NODE_TYPE_COLORS, EDGE_TYPE_COLORS } from './GraphLegend';
+
+const meta: Meta<typeof GraphLegend> = {
+  title: 'KFlow/Molecules/GraphLegend',
+  component: GraphLegend,
+  parameters: {
+    layout: 'padded',
+  },
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof GraphLegend>;
+
+export const Default: Story = {
+  args: {
+    items: [
+      { id: 'concept', label: 'Concept', color: NODE_TYPE_COLORS.concept },
+      { id: 'topic', label: 'Topic', color: NODE_TYPE_COLORS.topic },
+      { id: 'skill', label: 'Skill', color: NODE_TYPE_COLORS.skill },
+    ],
+  },
+};
+
+export const WithTitle: Story = {
+  args: {
+    title: 'Node Types',
+    items: [
+      { id: 'concept', label: 'Concept', color: NODE_TYPE_COLORS.concept },
+      { id: 'topic', label: 'Topic', color: NODE_TYPE_COLORS.topic },
+      { id: 'skill', label: 'Skill', color: NODE_TYPE_COLORS.skill },
+      { id: 'lesson', label: 'Lesson', color: NODE_TYPE_COLORS.lesson },
+    ],
+  },
+};
+
+export const WithCounts: Story = {
+  args: {
+    title: 'Graph Elements',
+    items: [
+      { id: 'concept', label: 'Concepts', color: NODE_TYPE_COLORS.concept, count: 24 },
+      { id: 'topic', label: 'Topics', color: NODE_TYPE_COLORS.topic, count: 8 },
+      { id: 'skill', label: 'Skills', color: NODE_TYPE_COLORS.skill, count: 15 },
+      { id: 'lesson', label: 'Lessons', color: NODE_TYPE_COLORS.lesson, count: 32 },
+    ],
+  },
+};
+
+export const Interactive: Story = {
+  args: {
+    title: 'Toggle Visibility',
+    interactive: true,
+    items: [
+      { id: 'concept', label: 'Concepts', color: NODE_TYPE_COLORS.concept, visible: true, count: 24 },
+      { id: 'topic', label: 'Topics', color: NODE_TYPE_COLORS.topic, visible: true, count: 8 },
+      { id: 'skill', label: 'Skills', color: NODE_TYPE_COLORS.skill, visible: false, count: 15 },
+      { id: 'lesson', label: 'Lessons', color: NODE_TYPE_COLORS.lesson, visible: true, count: 32 },
+    ],
+  },
+};
+
+export const Horizontal: Story = {
+  args: {
+    title: 'Edge Types',
+    direction: 'horizontal',
+    items: [
+      { id: 'prerequisite', label: 'Prerequisite', color: EDGE_TYPE_COLORS.prerequisite },
+      { id: 'related', label: 'Related', color: EDGE_TYPE_COLORS.related },
+      { id: 'contains', label: 'Contains', color: EDGE_TYPE_COLORS.contains },
+      { id: 'references', label: 'References', color: EDGE_TYPE_COLORS.references },
+    ],
+  },
+};
+
+export const EdgeTypes: Story = {
+  args: {
+    title: 'Connection Types',
+    items: [
+      { id: 'prerequisite', label: 'Prerequisite', color: EDGE_TYPE_COLORS.prerequisite, count: 45 },
+      { id: 'related', label: 'Related', color: EDGE_TYPE_COLORS.related, count: 28 },
+      { id: 'contains', label: 'Contains', color: EDGE_TYPE_COLORS.contains, count: 12 },
+    ],
+  },
+};
+
+export const FullGraph: Story = {
+  args: {
+    title: 'Knowledge Graph Legend',
+    interactive: true,
+    items: [
+      { id: 'concept', label: 'Concept', color: NODE_TYPE_COLORS.concept, visible: true, count: 156 },
+      { id: 'topic', label: 'Topic', color: NODE_TYPE_COLORS.topic, visible: true, count: 42 },
+      { id: 'skill', label: 'Skill', color: NODE_TYPE_COLORS.skill, visible: true, count: 89 },
+      { id: 'lesson', label: 'Lesson', color: NODE_TYPE_COLORS.lesson, visible: true, count: 234 },
+      { id: 'quiz', label: 'Quiz', color: NODE_TYPE_COLORS.quiz, visible: false, count: 67 },
+      { id: 'resource', label: 'Resource', color: NODE_TYPE_COLORS.resource, visible: true, count: 45 },
+    ],
+  },
+};

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

@@ -0,0 +1,120 @@
+/**
+ * GraphLegend - Legend for graph visualizations showing node/edge types
+ *
+ * Almadar Entity Binding:
+ * - Data flows through `items` prop
+ * - User interactions emit events via useEventBus()
+ *
+ * Events Emitted:
+ * - UI:TOGGLE_LEGEND_ITEM - When a legend item is clicked to toggle visibility
+ */
+
+import React from "react";
+import { Box } from "../../../components/atoms/Box";
+import { VStack } from "../../../components/atoms/Stack";
+import { HStack } from "../../../components/atoms/Stack";
+import { useEventBus } from "../../../hooks/useEventBus";
+
+export interface LegendItem {
+  id: string;
+  label: string;
+  color: string;
+  visible?: boolean;
+  count?: number;
+}
+
+export interface GraphLegendProps {
+  /** Legend items to display */
+  items: LegendItem[];
+  /** Title for the legend */
+  title?: string;
+  /** Whether items are interactive (toggleable) */
+  interactive?: boolean;
+  /** Layout direction */
+  direction?: "horizontal" | "vertical";
+  /** Additional CSS classes */
+  className?: string;
+}
+
+export const GraphLegend: React.FC<GraphLegendProps> = ({
+  items,
+  title,
+  interactive = false,
+  direction = "vertical",
+  className = "",
+}) => {
+  const { emit } = useEventBus();
+
+  const handleItemClick = (item: LegendItem) => {
+    if (interactive) {
+      emit("UI:TOGGLE_LEGEND_ITEM", {
+        itemId: item.id,
+        visible: !item.visible,
+      });
+    }
+  };
+
+  const Container = direction === "horizontal" ? HStack : VStack;
+
+  return (
+    <VStack
+      gap="sm"
+      className={`p-3 bg-white rounded-lg shadow-sm border border-gray-200 ${className}`}
+    >
+      {title && (
+        <span className="text-sm font-semibold text-gray-700">{title}</span>
+      )}
+      <Container gap="sm" wrap={direction === "horizontal"}>
+        {items.map((item) => (
+          <Box
+            key={item.id}
+            onClick={() => handleItemClick(item)}
+            className={`
+              ${interactive ? "cursor-pointer hover:bg-gray-50 rounded px-2 py-1 -mx-2" : ""}
+              ${item.visible === false ? "opacity-50" : ""}
+            `}
+          >
+            <HStack gap="sm" align="center">
+              <Box
+                className="w-4 h-4 rounded-full flex-shrink-0"
+                style={{ backgroundColor: item.color }}
+              />
+              <span className="text-sm text-gray-600">{item.label}</span>
+              {item.count !== undefined && (
+                <span className="text-xs text-gray-400 ml-1">
+                  ({item.count})
+                </span>
+              )}
+            </HStack>
+          </Box>
+        ))}
+      </Container>
+    </VStack>
+  );
+};
+
+GraphLegend.displayName = "GraphLegend";
+
+/**
+ * Default node type colors for knowledge graphs
+ */
+export const NODE_TYPE_COLORS: Record<string, string> = {
+  concept: "#6366f1", // indigo
+  topic: "#8b5cf6", // violet
+  skill: "#10b981", // emerald
+  lesson: "#f59e0b", // amber
+  quiz: "#ef4444", // red
+  resource: "#3b82f6", // blue
+  default: "#6b7280", // gray
+};
+
+/**
+ * Default edge type colors for knowledge graphs
+ */
+export const EDGE_TYPE_COLORS: Record<string, string> = {
+  prerequisite: "#ef4444", // red
+  related: "#6366f1", // indigo
+  contains: "#10b981", // emerald
+  references: "#3b82f6", // blue
+  default: "#9ca3af", // gray
+};