@almadar/cli 0.3.2 → 1.0.3

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

@@ -0,0 +1,301 @@
+/**
+ * ConceptCard - Displays a concept with header, description, metadata, and children
+ *
+ * Almadar Entity Binding:
+ * - Data flows through `entity` prop from Almadar state
+ * - User interactions emit events via useEventBus()
+ *
+ * Events Emitted:
+ * - UI:EXPAND_CONCEPT - When expand/collapse is toggled
+ * - UI:SELECT_CONCEPT - When concept is clicked
+ * - UI:CONCEPT_ACTION - When an action button is clicked
+ */
+
+import React, { useState } from "react";
+import {
+  ChevronDown,
+  ChevronRight,
+  BookOpen,
+  Check,
+  Circle,
+} from "lucide-react";
+import type { LucideIcon } 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 { useEventBus } from "../../../hooks/useEventBus";
+
+export interface ConceptEntity {
+  id: string;
+  name: string;
+  description?: string;
+  layer?: number;
+  prerequisites?: string[];
+  parents?: string[];
+  childConcepts?: ConceptEntity[];
+  progress?: number;
+  hasLesson?: boolean;
+  isCompleted?: boolean;
+  isCurrent?: boolean;
+}
+
+export interface ConceptCardProps {
+  /** Concept entity data */
+  entity?: ConceptEntity | string;
+  /** Whether this concept is highlighted (lesson ready) */
+  highlighted?: boolean;
+  /** Hide the lesson status badges */
+  hideLessonBadge?: boolean;
+  /** Optional icon */
+  icon?: LucideIcon;
+  /** Is expanded (showing children) */
+  expanded?: boolean;
+  /** Operation buttons */
+  operations?: Array<{
+    label: string;
+    icon?: LucideIcon;
+    action: string;
+    variant?: "primary" | "secondary" | "danger";
+  }>;
+  /** Additional CSS classes */
+  className?: string;
+  // Entity-aware props (for schema compatibility)
+  /** Data to display */
+  data?: unknown | unknown[];
+  /** Display variant */
+  variant?: string;
+  /** Item actions */
+  itemActions?: Array<{
+    label: string;
+    event: string;
+    onClick?: (row: Record<string, unknown>) => void;
+  }>;
+  /** Actions */
+  actions?: Array<{ label: string; event: string }>;
+  /** Fields to display */
+  displayFields?: string[];
+  /** Show children */
+  showChildren?: boolean;
+  /** Show flash cards */
+  showFlashCards?: boolean;
+  /** Show progress */
+  showProgress?: boolean;
+  /** Show lesson content */
+  showLessonContent?: boolean;
+}
+
+export const ConceptCard: React.FC<ConceptCardProps> = ({
+  entity: entityProp,
+  highlighted,
+  hideLessonBadge = false,
+  icon: IconComponent,
+  expanded: controlledExpanded,
+  operations,
+  className = "",
+}) => {
+  const { emit } = useEventBus();
+  const [internalExpanded, setInternalExpanded] = useState(false);
+
+  // Normalize entity - handle string, object, or undefined
+  const entity: ConceptEntity =
+    typeof entityProp === "string"
+      ? { id: entityProp, name: entityProp }
+      : (entityProp ?? { id: "unknown", name: "Unknown" });
+
+  const expanded =
+    controlledExpanded !== undefined ? controlledExpanded : internalExpanded;
+  const hasChildren =
+    Array.isArray(entity.childConcepts) && entity.childConcepts.length > 0;
+
+  const isHighlighted = highlighted ?? entity.hasLesson;
+  const { isCompleted, isCurrent } = entity;
+
+  const handleExpand = (e: React.MouseEvent) => {
+    e.stopPropagation();
+    if (hasChildren) {
+      const newExpanded = !expanded;
+      if (controlledExpanded === undefined) {
+        setInternalExpanded(newExpanded);
+      }
+      emit("UI:EXPAND_CONCEPT", {
+        conceptId: entity.id,
+        expanded: newExpanded,
+      });
+    }
+  };
+
+  const handleClick = () => {
+    emit("UI:SELECT_CONCEPT", { conceptId: entity.id, entity });
+  };
+
+  const handleAction = (action: string, e: React.MouseEvent) => {
+    e.stopPropagation();
+    emit("UI:CONCEPT_ACTION", { conceptId: entity.id, action });
+  };
+
+  const getCardStyle = () => {
+    const baseStyle = "transition-all duration-200 border-l-4 cursor-pointer";
+    if (isCompleted) return `${baseStyle} opacity-60 border-l-gray-300`;
+    if (isCurrent)
+      return `${baseStyle} ring-2 ring-indigo-500 border-l-indigo-500 bg-indigo-50`;
+    if (isHighlighted) return `${baseStyle} border-l-emerald-500 bg-emerald-50`;
+    return `${baseStyle} border-l-gray-200`;
+  };
+
+  const getStatusIcon = () => {
+    if (isCompleted) return <Check size={18} className="text-white" />;
+    if (isHighlighted) return <BookOpen size={16} className="text-white" />;
+    return <Circle size={18} className="text-gray-500" />;
+  };
+
+  const getStatusBgColor = () => {
+    if (isCompleted) return "bg-green-500";
+    if (isCurrent) return "bg-indigo-500";
+    if (isHighlighted) return "bg-emerald-500";
+    return "bg-gray-200";
+  };
+
+  return (
+    <Card
+      className={`shadow-md ${getCardStyle()} ${className}`}
+      onClick={handleClick}
+    >
+      <VStack gap="sm">
+        {/* Header */}
+        <HStack gap="sm" align="start">
+          {hasChildren && (
+            <button
+              type="button"
+              onClick={handleExpand}
+              className="flex-shrink-0 mt-1 p-1 hover:bg-gray-100 rounded"
+            >
+              {expanded ? (
+                <ChevronDown size={16} className="text-gray-500" />
+              ) : (
+                <ChevronRight size={16} className="text-gray-500" />
+              )}
+            </button>
+          )}
+
+          {/* Status indicator */}
+          {!IconComponent && (
+            <Box
+              className={`flex-shrink-0 w-8 h-8 rounded-full flex items-center justify-center ${getStatusBgColor()}`}
+            >
+              {getStatusIcon()}
+            </Box>
+          )}
+
+          {IconComponent && (
+            <Box className="flex-shrink-0">
+              <IconComponent size={24} className="text-gray-600" />
+            </Box>
+          )}
+
+          <VStack gap="xs" className="flex-1 min-w-0">
+            <HStack gap="sm" align="center">
+              <span className="font-semibold text-gray-900">{entity.name}</span>
+              {!hideLessonBadge && isHighlighted && !isCompleted && (
+                <span className="px-2 py-0.5 text-xs font-medium bg-emerald-100 text-emerald-700 rounded">
+                  Lesson Ready
+                </span>
+              )}
+              {!hideLessonBadge && !isHighlighted && !isCompleted && (
+                <span className="px-2 py-0.5 text-xs font-medium bg-gray-100 text-gray-600 rounded">
+                  No Lesson
+                </span>
+              )}
+            </HStack>
+
+            {entity.description && (
+              <p className="text-sm text-gray-600">{entity.description}</p>
+            )}
+
+            {/* Prerequisites */}
+            {entity.prerequisites && entity.prerequisites.length > 0 && (
+              <HStack gap="xs" wrap className="mt-1">
+                <span className="text-xs font-semibold text-indigo-600">
+                  Prerequisites:
+                </span>
+                {entity.prerequisites.map((prereq, idx) => (
+                  <span
+                    key={idx}
+                    className="px-2 py-0.5 text-xs font-medium bg-indigo-100 text-indigo-700 rounded"
+                  >
+                    {prereq}
+                  </span>
+                ))}
+              </HStack>
+            )}
+
+            {/* Parents */}
+            {entity.parents && entity.parents.length > 0 && (
+              <HStack gap="xs" wrap className="mt-1">
+                <span className="text-xs text-gray-500">Parents:</span>
+                {entity.parents.map((parent, idx) => (
+                  <span
+                    key={idx}
+                    className="px-2 py-0.5 text-xs font-medium bg-gray-100 text-gray-700 rounded"
+                  >
+                    {parent}
+                  </span>
+                ))}
+              </HStack>
+            )}
+          </VStack>
+        </HStack>
+
+        {/* Progress Bar */}
+        {entity.progress !== undefined && (
+          <Box className="w-full h-2 bg-gray-200 rounded-full overflow-hidden">
+            <Box
+              className="h-full bg-indigo-500 transition-all"
+              style={{ width: `${entity.progress}%` }}
+            />
+          </Box>
+        )}
+
+        {/* Operations */}
+        {operations && operations.length > 0 && (
+          <HStack gap="sm">
+            {operations.map((op, idx) => {
+              const OpIcon = op.icon;
+              return (
+                <button
+                  key={idx}
+                  className={`px-3 py-1.5 text-sm font-medium rounded flex items-center gap-1 ${
+                    op.variant === "primary"
+                      ? "bg-indigo-600 text-white hover:bg-indigo-700"
+                      : op.variant === "danger"
+                        ? "bg-red-600 text-white hover:bg-red-700"
+                        : "bg-gray-100 text-gray-700 hover:bg-gray-200"
+                  }`}
+                  onClick={(e) => handleAction(op.action, e)}
+                >
+                  {OpIcon && <OpIcon size={14} />}
+                  {op.label}
+                </button>
+              );
+            })}
+          </HStack>
+        )}
+
+        {/* Children */}
+        {hasChildren && expanded && entity.childConcepts && (
+          <VStack gap="sm" className="pl-6 border-l-2 border-gray-200 mt-2">
+            {entity.childConcepts.map((child) => (
+              <ConceptCard
+                key={child.id}
+                entity={child}
+                hideLessonBadge={hideLessonBadge}
+              />
+            ))}
+          </VStack>
+        )}
+      </VStack>
+    </Card>
+  );
+};
+
+ConceptCard.displayName = "ConceptCard";

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

@@ -0,0 +1,105 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { FlashCard } from './FlashCard';
+
+const meta: Meta<typeof FlashCard> = {
+  title: 'KFlow/Organisms/FlashCard',
+  component: FlashCard,
+  parameters: {
+    layout: 'centered',
+  },
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof FlashCard>;
+
+export const Default: Story = {
+  args: {
+    entity: {
+      id: 'card-1',
+      front: 'What is the capital of France?',
+      back: 'Paris',
+    },
+  },
+};
+
+export const Flipped: Story = {
+  args: {
+    entity: {
+      id: 'card-2',
+      front: 'What is 2 + 2?',
+      back: '4',
+    },
+    flipped: true,
+  },
+};
+
+export const Studied: Story = {
+  args: {
+    entity: {
+      id: 'card-3',
+      front: 'What is the chemical symbol for water?',
+      back: 'H₂O',
+      studied: true,
+    },
+    flipped: true,
+  },
+};
+
+export const WithProgress: Story = {
+  args: {
+    entity: {
+      id: 'card-4',
+      front: 'What is the speed of light?',
+      back: '299,792,458 m/s',
+    },
+    currentCard: 5,
+    totalCards: 10,
+  },
+};
+
+export const NoActions: Story = {
+  args: {
+    entity: {
+      id: 'card-5',
+      front: 'What year did World War II end?',
+      back: '1945',
+    },
+    showActions: false,
+  },
+};
+
+export const NoNavigation: Story = {
+  args: {
+    entity: {
+      id: 'card-6',
+      front: 'What is the largest planet in our solar system?',
+      back: 'Jupiter',
+    },
+    showNavigation: false,
+  },
+};
+
+export const MinimalMode: Story = {
+  args: {
+    entity: {
+      id: 'card-7',
+      front: 'What is the formula for the area of a circle?',
+      back: 'πr²',
+    },
+    showActions: false,
+    showNavigation: false,
+  },
+};
+
+export const LongContent: Story = {
+  args: {
+    entity: {
+      id: 'card-8',
+      front: 'Explain the concept of object-oriented programming and its main principles.',
+      back: 'OOP is a programming paradigm based on objects containing data and methods. Main principles: Encapsulation, Inheritance, Polymorphism, and Abstraction.',
+    },
+    currentCard: 8,
+    totalCards: 20,
+  },
+};

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

@@ -0,0 +1,200 @@
+/**
+ * FlashCard - A flashcard component with flip animation and navigation
+ *
+ * Almadar Entity Binding:
+ * - Data flows through `entity` prop from Almadar state
+ * - User interactions emit events via useEventBus()
+ *
+ * Events Emitted:
+ * - UI:FLIP_CARD - When card is flipped
+ * - UI:MARK_STUDIED - When marked as studied
+ * - UI:RESET_CARD - When card is reset
+ * - UI:NEXT_CARD - When navigating to next card
+ * - UI:PREV_CARD - When navigating to previous card
+ */
+
+import React, { useState } from 'react';
+import { RotateCcw, Check } from 'lucide-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 FlashCardEntity {
+  id: string;
+  front: string;
+  back: string;
+  studied?: boolean;
+}
+
+export interface FlashCardProps {
+  /** Flash card entity data */
+  entity: FlashCardEntity;
+  /** Is flipped (controlled) */
+  flipped?: boolean;
+  /** Current card number (for progress) */
+  currentCard?: number;
+  /** Total cards (for progress) */
+  totalCards?: number;
+  /** Show navigation buttons */
+  showNavigation?: boolean;
+  /** Show study actions */
+  showActions?: boolean;
+  /** Additional CSS classes */
+  className?: string;
+}
+
+export const FlashCard: React.FC<FlashCardProps> = ({
+  entity,
+  flipped: controlledFlipped,
+  currentCard,
+  totalCards,
+  showNavigation = true,
+  showActions = true,
+  className = '',
+}) => {
+  const { emit } = useEventBus();
+  const [internalFlipped, setInternalFlipped] = useState(false);
+  const flipped = controlledFlipped !== undefined ? controlledFlipped : internalFlipped;
+
+  const progress =
+    currentCard && totalCards ? (currentCard / totalCards) * 100 : undefined;
+
+  const handleFlip = () => {
+    const newFlipped = !flipped;
+    if (controlledFlipped === undefined) {
+      setInternalFlipped(newFlipped);
+    }
+    emit('UI:FLIP_CARD', { cardId: entity.id, flipped: newFlipped });
+  };
+
+  const handleMarkStudied = (e: React.MouseEvent) => {
+    e.stopPropagation();
+    emit('UI:MARK_STUDIED', { cardId: entity.id });
+  };
+
+  const handleReset = (e: React.MouseEvent) => {
+    e.stopPropagation();
+    emit('UI:RESET_CARD', { cardId: entity.id });
+  };
+
+  const handleNext = () => {
+    emit('UI:NEXT_CARD', { currentCardId: entity.id });
+  };
+
+  const handlePrev = () => {
+    emit('UI:PREV_CARD', { currentCardId: entity.id });
+  };
+
+  return (
+    <VStack gap="md" className={`w-full max-w-md mx-auto ${className}`}>
+      {/* Progress */}
+      {progress !== undefined && (
+        <VStack gap="xs">
+          <HStack justify="between">
+            <span className="text-sm text-gray-500">
+              Card {currentCard} of {totalCards}
+            </span>
+            <span className="text-sm text-gray-500">{Math.round(progress)}%</span>
+          </HStack>
+          <Box className="w-full h-2 bg-gray-200 rounded-full overflow-hidden">
+            <Box
+              className="h-full bg-indigo-500 transition-all"
+              style={{ width: `${progress}%` }}
+            />
+          </Box>
+        </VStack>
+      )}
+
+      {/* Flashcard */}
+      <Box
+        className="relative w-full h-64 cursor-pointer"
+        style={{ perspective: '1000px' }}
+        onClick={handleFlip}
+      >
+        <Box
+          className="relative w-full h-full transition-transform duration-500"
+          style={{
+            transformStyle: 'preserve-3d',
+            transform: flipped ? 'rotateY(180deg)' : 'rotateY(0deg)',
+          }}
+        >
+          {/* Front Side */}
+          <Box
+            className="absolute inset-0 w-full h-full bg-white rounded-lg shadow-lg flex items-center justify-center p-6"
+            style={{ backfaceVisibility: 'hidden', transform: 'rotateY(0deg)' }}
+          >
+            <VStack gap="sm" align="center" className="text-center">
+              <span className="text-sm text-gray-500">Question</span>
+              <span className="text-xl font-semibold text-gray-900">
+                {entity.front}
+              </span>
+              <span className="text-sm text-gray-400">Click to flip</span>
+            </VStack>
+          </Box>
+
+          {/* Back Side */}
+          <Box
+            className="absolute inset-0 w-full h-full bg-white rounded-lg shadow-lg flex items-center justify-center p-6"
+            style={{
+              backfaceVisibility: 'hidden',
+              transform: 'rotateY(180deg)',
+            }}
+          >
+            <VStack gap="sm" align="center" className="text-center">
+              <span className="text-sm text-gray-500">Answer</span>
+              <span className="text-xl font-semibold text-gray-900">
+                {entity.back}
+              </span>
+              {entity.studied && (
+                <span className="px-2 py-1 text-xs font-medium bg-green-100 text-green-700 rounded mt-2">
+                  Studied
+                </span>
+              )}
+            </VStack>
+          </Box>
+        </Box>
+      </Box>
+
+      {/* Actions */}
+      {showActions && (
+        <HStack gap="sm" justify="center">
+          <button
+            className="px-4 py-2 text-sm font-medium bg-green-600 text-white rounded hover:bg-green-700 flex items-center gap-2"
+            onClick={handleMarkStudied}
+          >
+            <Check size={16} />
+            Mark as Studied
+          </button>
+          <button
+            className="px-4 py-2 text-sm font-medium bg-gray-100 text-gray-700 rounded hover:bg-gray-200 flex items-center gap-2"
+            onClick={handleReset}
+          >
+            <RotateCcw size={16} />
+            Reset
+          </button>
+        </HStack>
+      )}
+
+      {/* Navigation */}
+      {showNavigation && (
+        <HStack gap="sm" justify="center">
+          <button
+            className="px-4 py-2 text-sm font-medium bg-gray-100 text-gray-700 rounded hover:bg-gray-200"
+            onClick={handlePrev}
+          >
+            Previous
+          </button>
+          <button
+            className="px-4 py-2 text-sm font-medium bg-indigo-600 text-white rounded hover:bg-indigo-700"
+            onClick={handleNext}
+          >
+            Next
+          </button>
+        </HStack>
+      )}
+    </VStack>
+  );
+};
+
+FlashCard.displayName = 'FlashCard';

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

@@ -0,0 +1,97 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { FlashCardStack } from './FlashCardStack';
+
+const meta: Meta<typeof FlashCardStack> = {
+  title: 'KFlow/Organisms/FlashCardStack',
+  component: FlashCardStack,
+  parameters: {
+    layout: 'centered',
+  },
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof FlashCardStack>;
+
+const sampleCards = [
+  { id: '1', front: 'What is the capital of France?', back: 'Paris' },
+  { id: '2', front: 'What is 2 + 2?', back: '4' },
+  { id: '3', front: 'What is H₂O?', back: 'Water' },
+  { id: '4', front: 'What planet is known as the Red Planet?', back: 'Mars' },
+  { id: '5', front: 'Who wrote Romeo and Juliet?', back: 'William Shakespeare' },
+];
+
+export const Default: Story = {
+  args: {
+    cards: sampleCards,
+  },
+};
+
+export const Empty: Story = {
+  args: {
+    cards: [],
+  },
+};
+
+export const SingleCard: Story = {
+  args: {
+    cards: [{ id: '1', front: 'Only one card', back: 'Just this one!' }],
+  },
+};
+
+export const PartiallyStudied: Story = {
+  args: {
+    cards: [
+      { id: '1', front: 'Studied card 1', back: 'Answer 1', studied: true },
+      { id: '2', front: 'Studied card 2', back: 'Answer 2', studied: true },
+      { id: '3', front: 'Not studied yet', back: 'Answer 3' },
+      { id: '4', front: 'Also not studied', back: 'Answer 4' },
+      { id: '5', front: 'Need to study this', back: 'Answer 5' },
+    ],
+    currentIndex: 2,
+  },
+};
+
+export const AllStudied: Story = {
+  args: {
+    cards: sampleCards.map((card) => ({ ...card, studied: true })),
+  },
+};
+
+export const NoShuffle: Story = {
+  args: {
+    cards: sampleCards,
+    showShuffle: false,
+  },
+};
+
+export const NoSummary: Story = {
+  args: {
+    cards: sampleCards.map((card) => ({ ...card, studied: true })),
+    showSummary: false,
+  },
+};
+
+export const ManyCards: Story = {
+  args: {
+    cards: Array.from({ length: 20 }, (_, i) => ({
+      id: `card-${i + 1}`,
+      front: `Question ${i + 1}`,
+      back: `Answer ${i + 1}`,
+      studied: i < 7,
+    })),
+    currentIndex: 7,
+  },
+};
+
+export const MathCards: Story = {
+  args: {
+    cards: [
+      { id: '1', front: 'What is the derivative of x²?', back: '2x' },
+      { id: '2', front: 'What is ∫x dx?', back: 'x²/2 + C' },
+      { id: '3', front: 'What is sin²θ + cos²θ?', back: '1' },
+      { id: '4', front: 'What is the quadratic formula?', back: 'x = (-b ± √(b²-4ac)) / 2a' },
+      { id: '5', front: 'What is e^(iπ) + 1?', back: '0 (Euler\'s identity)' },
+    ],
+  },
+};