qnce-engine 1.2.0 → 1.2.2

package/examples/ui-components-demo.tsx

@@ -0,0 +1,320 @@
+import React, { useState } from 'react';
+import { createRoot } from 'react-dom/client';
+import { 
+  createQNCEEngine, 
+  DEMO_STORY,
+  useQNCE,
+  UndoRedoControls,
+  AutosaveIndicator,
+  useKeyboardShortcuts
+} from '../src/index';
+
+/**
+ * QNCE Engine UI Components Demo
+ * Sprint 3.6: Demonstrates autosave indicators, undo/redo controls, and keyboard shortcuts
+ * 
+ * Features showcased:
+ * - UndoRedoControls component with different layouts and themes
+ * - AutosaveIndicator with various configurations
+ * - Keyboard shortcuts integration
+ * - Real-time state updates and visual feedback
+ * - Accessibility features
+ */
+
+const QNCEDemo: React.FC = () => {
+  const [engine] = useState(() => createQNCEEngine(DEMO_STORY));
+  const { currentNode, availableChoices, flags, selectChoice, resetNarrative } = useQNCE(engine);
+
+  // Enable keyboard shortcuts
+  useKeyboardShortcuts(engine, {
+    enabled: true,
+    bindings: {
+      undo: ['ctrl+z', 'cmd+z'],
+      redo: ['ctrl+y', 'cmd+y', 'ctrl+shift+z'],
+      save: ['ctrl+s', 'cmd+s'],
+      reset: ['ctrl+r'] // Enable reset with confirmation
+    }
+  });
+
+  const [showAdvanced, setShowAdvanced] = useState(false);
+
+  const appStyle: React.CSSProperties = {
+    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
+    maxWidth: '800px',
+    margin: '0 auto',
+    padding: '2rem',
+    lineHeight: 1.6,
+    color: '#333'
+  };
+
+  const headerStyle: React.CSSProperties = {
+    textAlign: 'center',
+    marginBottom: '2rem',
+    padding: '1rem',
+    backgroundColor: '#f8f9fa',
+    borderRadius: '8px',
+    border: '1px solid #e9ecef'
+  };
+
+  const sectionStyle: React.CSSProperties = {
+    marginBottom: '2rem',
+    padding: '1rem',
+    backgroundColor: '#ffffff',
+    borderRadius: '8px',
+    border: '1px solid #e9ecef',
+    boxShadow: '0 2px 4px rgba(0,0,0,0.1)'
+  };
+
+  const narrativeStyle: React.CSSProperties = {
+    fontSize: '1.1rem',
+    lineHeight: 1.8,
+    marginBottom: '1rem',
+    padding: '1rem',
+    backgroundColor: '#f8f9fa',
+    borderLeft: '4px solid #007bff',
+    borderRadius: '0 4px 4px 0'
+  };
+
+  const choiceButtonStyle: React.CSSProperties = {
+    display: 'block',
+    width: '100%',
+    padding: '0.75rem 1rem',
+    margin: '0.5rem 0',
+    fontSize: '1rem',
+    backgroundColor: '#007bff',
+    color: 'white',
+    border: 'none',
+    borderRadius: '4px',
+    cursor: 'pointer',
+    transition: 'background-color 0.2s'
+  };
+
+  const controlsContainerStyle: React.CSSProperties = {
+    display: 'flex',
+    gap: '1rem',
+    alignItems: 'center',
+    flexWrap: 'wrap',
+    padding: '1rem',
+    backgroundColor: '#f8f9fa',
+    borderRadius: '8px',
+    marginBottom: '1rem'
+  };
+
+  const flagsStyle: React.CSSProperties = {
+    fontSize: '0.9rem',
+    color: '#6c757d',
+    backgroundColor: '#e9ecef',
+    padding: '0.5rem',
+    borderRadius: '4px',
+    fontFamily: 'monospace'
+  };
+
+  return (
+    <div style={appStyle}>
+      {/* Header */}
+      <header style={headerStyle}>
+        <h1>🎮 QNCE Engine UI Components Demo</h1>
+        <p>Sprint 3.6: Interactive showcase of autosave indicators, undo/redo controls, and keyboard shortcuts</p>
+        <p style={{ fontSize: '0.9rem', color: '#6c757d' }}>
+          <strong>Keyboard shortcuts:</strong> Ctrl/Cmd+Z (Undo), Ctrl/Cmd+Y (Redo), Ctrl/Cmd+S (Save)
+        </p>
+      </header>
+
+      {/* Controls Section */}
+      <section style={sectionStyle}>
+        <h2>🎛️ Controls & Status</h2>
+        <div style={controlsContainerStyle}>
+          {/* Autosave Indicator */}
+          <AutosaveIndicator 
+            engine={engine}
+            variant="detailed"
+            showTimestamp={true}
+            autoHideDelay={3000}
+          />
+
+          {/* Undo/Redo Controls - Horizontal Layout */}
+          <UndoRedoControls
+            engine={engine}
+            size="md"
+            layout="horizontal"
+            showLabels={true}
+            onUndo={() => console.log('Undo performed')}
+            onRedo={() => console.log('Redo performed')}
+          />
+
+          {/* Reset Button */}
+          <button
+            onClick={resetNarrative}
+            style={{
+              padding: '0.5rem 1rem',
+              backgroundColor: '#dc3545',
+              color: 'white',
+              border: 'none',
+              borderRadius: '4px',
+              cursor: 'pointer'
+            }}
+          >
+            Reset
+          </button>
+
+          {/* Toggle Advanced View */}
+          <button
+            onClick={() => setShowAdvanced(!showAdvanced)}
+            style={{
+              padding: '0.5rem 1rem',
+              backgroundColor: '#6c757d',
+              color: 'white',
+              border: 'none',
+              borderRadius: '4px',
+              cursor: 'pointer'
+            }}
+          >
+            {showAdvanced ? 'Hide' : 'Show'} Advanced
+          </button>
+        </div>
+      </section>
+
+      {/* Advanced Controls (when enabled) */}
+      {showAdvanced && (
+        <section style={sectionStyle}>
+          <h3>🔧 Advanced Controls</h3>
+          <div style={{ display: 'flex', gap: '1rem', alignItems: 'center', flexWrap: 'wrap' }}>
+            {/* Vertical Layout Undo/Redo */}
+            <div>
+              <h4 style={{ margin: '0 0 0.5rem 0', fontSize: '0.9rem' }}>Vertical Layout</h4>
+              <UndoRedoControls
+                engine={engine}
+                size="sm"
+                layout="vertical"
+                showLabels={false}
+              />
+            </div>
+
+            {/* Large Size Controls */}
+            <div>
+              <h4 style={{ margin: '0 0 0.5rem 0', fontSize: '0.9rem' }}>Large Size</h4>
+              <UndoRedoControls
+                engine={engine}
+                size="lg"
+                layout="horizontal"
+                showLabels={true}
+                theme={{
+                  colors: {
+                    primary: '#28a745',
+                    background: '#ffffff'
+                  }
+                }}
+              />
+            </div>
+
+            {/* Icon-only Autosave */}
+            <div>
+              <h4 style={{ margin: '0 0 0.5rem 0', fontSize: '0.9rem' }}>Icon-only</h4>
+              <AutosaveIndicator 
+                engine={engine}
+                variant="icon-only"
+                showTimestamp={false}
+              />
+            </div>
+
+            {/* Minimal Autosave */}
+            <div>
+              <h4 style={{ margin: '0 0 0.5rem 0', fontSize: '0.9rem' }}>Minimal</h4>
+              <AutosaveIndicator 
+                engine={engine}
+                variant="minimal"
+                showTimestamp={false}
+                theme={{
+                  colors: {
+                    success: '#17a2b8',
+                    warning: '#ffc107'
+                  }
+                }}
+              />
+            </div>
+          </div>
+        </section>
+      )}
+
+      {/* Narrative Section */}
+      <section style={sectionStyle}>
+        <h2>📖 Current Scene</h2>
+        <div style={narrativeStyle}>
+          {currentNode.text}
+        </div>
+
+        {/* Choices */}
+        {availableChoices.length > 0 && (
+          <div>
+            <h3>Choose your path:</h3>
+            {availableChoices.map((choice, index) => (
+              <button
+                key={index}
+                onClick={() => selectChoice(choice)}
+                style={choiceButtonStyle}
+                onMouseEnter={(e) => {
+                  e.currentTarget.style.backgroundColor = '#0056b3';
+                }}
+                onMouseLeave={(e) => {
+                  e.currentTarget.style.backgroundColor = '#007bff';
+                }}
+              >
+                {choice.text}
+              </button>
+            ))}
+          </div>
+        )}
+
+        {/* End of story message */}
+        {availableChoices.length === 0 && (
+          <div style={{ textAlign: 'center', padding: '2rem' }}>
+            <h3>🎊 The End</h3>
+            <p>You've reached the end of this narrative path.</p>
+            <button
+              onClick={resetNarrative}
+              style={{
+                ...choiceButtonStyle,
+                backgroundColor: '#28a745',
+                width: 'auto',
+                display: 'inline-block'
+              }}
+            >
+              Start Over
+            </button>
+          </div>
+        )}
+      </section>
+
+      {/* Story State Info */}
+      <section style={sectionStyle}>
+        <h3>📊 Story State</h3>
+        <div style={flagsStyle}>
+          <strong>Current Node:</strong> {currentNode.id}<br/>
+          <strong>Flags:</strong> {Object.keys(flags).length > 0 ? JSON.stringify(flags, null, 2) : 'None set'}
+        </div>
+      </section>
+
+      {/* Instructions */}
+      <section style={sectionStyle}>
+        <h3>💡 Usage Instructions</h3>
+        <ul style={{ lineHeight: 1.8 }}>
+          <li><strong>Make choices</strong> to progress through the story and see autosave indicators</li>
+          <li><strong>Use keyboard shortcuts:</strong> Ctrl/Cmd+Z to undo, Ctrl/Cmd+Y to redo, Ctrl/Cmd+S to save</li>
+          <li><strong>Watch the autosave indicator</strong> show status changes in real-time</li>
+          <li><strong>Try the undo/redo buttons</strong> to navigate through your choice history</li>
+          <li><strong>Toggle advanced view</strong> to see different component variations</li>
+          <li><strong>All components are accessible</strong> with keyboard navigation and screen readers</li>
+        </ul>
+      </section>
+    </div>
+  );
+};
+
+// Initialize the demo
+const container = document.getElementById('root');
+if (container) {
+  const root = createRoot(container);
+  root.render(<QNCEDemo />);
+} else {
+  console.error('Root container not found');
+}

package/examples/validation-demo-story.json

@@ -0,0 +1,177 @@
+{
+  "initialNodeId": "entrance",
+  "nodes": [
+    {
+      "id": "entrance",
+      "text": "You stand before an ancient castle. The heavy oak doors are locked, and storm clouds gather overhead.",
+      "choices": [
+        {
+          "text": "Try to force the door open",
+          "nextNodeId": "door_attempt"
+        },
+        {
+          "text": "Use the golden key",
+          "nextNodeId": "unlock_door",
+          "flagRequirements": {
+            "hasGoldenKey": true
+          }
+        },
+        {
+          "text": "Wait outside in the storm",
+          "nextNodeId": "storm_wait",
+          "enabled": false
+        },
+        {
+          "text": "Purchase a lockpick from the merchant",
+          "nextNodeId": "buy_lockpick",
+          "inventoryRequirements": {
+            "gold": 25,
+            "reputation": 5
+          }
+        },
+        {
+          "text": "Visit the tavern (opens at sunset)",
+          "nextNodeId": "tavern",
+          "timeRequirements": {
+            "availableAfter": "2025-01-01T18:00:00.000Z",
+            "availableBefore": "2025-01-01T23:59:59.000Z"
+          }
+        }
+      ]
+    },
+    {
+      "id": "door_attempt",
+      "text": "You push against the heavy doors, but they remain firmly shut. Your shoulder aches from the effort.",
+      "choices": [
+        {
+          "text": "Return to the entrance",
+          "nextNodeId": "entrance"
+        }
+      ]
+    },
+    {
+      "id": "unlock_door",
+      "text": "The golden key turns smoothly in the lock. The doors swing open with a satisfying creak, revealing a grand hallway beyond.",
+      "choices": [
+        {
+          "text": "Enter the castle",
+          "nextNodeId": "grand_hall",
+          "flagEffects": {
+            "enteredCastle": true
+          }
+        }
+      ]
+    },
+    {
+      "id": "storm_wait",
+      "text": "You decide to wait outside, but this choice should never be reachable due to validation.",
+      "choices": []
+    },
+    {
+      "id": "buy_lockpick",
+      "text": "The merchant smiles as you purchase a masterfully crafted lockpick. 'This will open any door,' he promises.",
+      "choices": [
+        {
+          "text": "Return to the entrance with lockpick",
+          "nextNodeId": "entrance",
+          "flagEffects": {
+            "hasLockpick": true
+          }
+        }
+      ]
+    },
+    {
+      "id": "tavern",
+      "text": "The warm tavern glows with candlelight. Travelers share stories and the aroma of roasted meat fills the air.",
+      "choices": [
+        {
+          "text": "Listen to the bard's tale",
+          "nextNodeId": "bard_story"
+        },
+        {
+          "text": "Ask about the castle",
+          "nextNodeId": "castle_info"
+        }
+      ]
+    },
+    {
+      "id": "grand_hall",
+      "text": "You stand in an opulent grand hall with marble columns and tapestries depicting ancient battles.",
+      "choices": [
+        {
+          "text": "Explore the east wing",
+          "nextNodeId": "east_wing"
+        },
+        {
+          "text": "Climb the grand staircase",
+          "nextNodeId": "upper_floor"
+        }
+      ]
+    },
+    {
+      "id": "bard_story",
+      "text": "The bard tells of a legendary treasure hidden deep within the castle, guarded by ancient magic.",
+      "choices": [
+        {
+          "text": "Ask about the treasure",
+          "nextNodeId": "treasure_info",
+          "flagEffects": {
+            "knowsAboutTreasure": true
+          }
+        }
+      ]
+    },
+    {
+      "id": "castle_info",
+      "text": "A grizzled traveler warns you about the castle's dangers but mentions a golden key hidden in the forest.",
+      "choices": [
+        {
+          "text": "Ask where to find the key",
+          "nextNodeId": "key_location",
+          "flagEffects": {
+            "knowsKeyLocation": true
+          }
+        }
+      ]
+    },
+    {
+      "id": "treasure_info",
+      "text": "The bard leans closer and whispers the secret of the treasure's location...",
+      "choices": []
+    },
+    {
+      "id": "key_location",
+      "text": "The traveler draws a rough map on a napkin, marking where the golden key lies buried.",
+      "choices": [
+        {
+          "text": "Search for the key",
+          "nextNodeId": "find_key",
+          "flagEffects": {
+            "hasGoldenKey": true,
+            "foundKey": true
+          }
+        }
+      ]
+    },
+    {
+      "id": "find_key",
+      "text": "After searching through the undergrowth, your fingers close around a cold, golden key. Success!",
+      "choices": [
+        {
+          "text": "Return to the castle",
+          "nextNodeId": "entrance"
+        }
+      ]
+    },
+    {
+      "id": "east_wing",
+      "text": "The east wing is filled with ancient artifacts and dusty paintings.",
+      "choices": []
+    },
+    {
+      "id": "upper_floor",
+      "text": "The upper floor overlooks the grand hall. Moonlight streams through stained glass windows.",
+      "choices": []
+    }
+  ]
+}

package/examples/validation-demo.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+
+// QNCE Choice Validation Demo
+// Demonstrates the choice validation system with various error scenarios
+
+import { 
+  createQNCEEngine, 
+  ChoiceValidationError, 
+  isChoiceValidationError,
+  createChoiceValidator,
+  StandardValidationRules 
+} from '../src/engine/core.js';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Load the validation demo story
+const storyPath = path.join(__dirname, 'validation-demo-story.json');
+const storyData = JSON.parse(fs.readFileSync(storyPath, 'utf8'));
+
+console.log('🛡️ QNCE Choice Validation Demo');
+console.log('=====================================\n');
+
+// Create engine with demo story
+const engine = createQNCEEngine(storyData);
+
+function displayCurrentState() {
+  const currentNode = engine.getCurrentNode();
+  const availableChoices = engine.getAvailableChoices();
+  
+  console.log(`\n📍 Current Location: ${currentNode.id}`);
+  console.log(`📝 ${currentNode.text}\n`);
+  
+  console.log('✅ Available Choices:');
+  availableChoices.forEach((choice, index) => {
+    console.log(`  ${index + 1}. ${choice.text}`);
+  });
+  
+  if (availableChoices.length === 0) {
+    console.log('  (No choices available - story complete)');
+  }
+  
+  // Show current state
+  const state = engine.getState();
+  console.log(`\n🏷️  Current Flags: ${JSON.stringify(state.flags, null, 2)}`);
+}
+
+function demonstrateValidationError(choiceIndex, errorType) {
+  console.log(`\n❌ Testing ${errorType}...`);
+  try {
+    engine.makeChoice(choiceIndex);
+    console.log('✅ Choice executed successfully (unexpected!)');
+  } catch (error) {
+    if (isChoiceValidationError(error)) {
+      console.log(`🚫 ChoiceValidationError caught: ${error.message}`);
+      console.log(`📋 Failed conditions: ${error.validationResult.failedConditions?.join(', ') || 'none'}`);
+      
+      const userMessage = error.getUserFriendlyMessage();
+      console.log(`👤 User-friendly message:\n${userMessage}`);
+      
+      const debugInfo = error.getDebugInfo();
+      console.log(`🔧 Debug info: ${JSON.stringify(debugInfo, null, 2)}`);
+    } else {
+      console.log(`❗ Other error: ${error.message}`);
+    }
+  }
+}
+
+async function runDemo() {
+  try {
+    // Display initial state
+    displayCurrentState();
+    
+    // Test 1: Try a valid choice first
+    console.log('\n🧪 Test 1: Valid Choice');
+    console.log('Attempting choice 1 (Try to force the door open)...');
+    engine.makeChoice(0);
+    displayCurrentState();
+    
+    // Reset to entrance
+    engine.goToNodeById('entrance');
+    displayCurrentState();
+    
+    // Test 2: Flag requirement failure
+    console.log('\n🧪 Test 2: Flag Requirement Failure');
+    demonstrateValidationError(1, 'missing flag requirement (hasGoldenKey)');
+    
+    // Test 3: Disabled choice
+    console.log('\n🧪 Test 3: Disabled Choice');
+    demonstrateValidationError(2, 'disabled choice');
+    
+    // Test 4: Inventory requirement failure
+    console.log('\n🧪 Test 4: Inventory Requirement Failure');
+    demonstrateValidationError(3, 'insufficient inventory (gold and reputation)');
+    
+    // Test 5: Time requirement failure
+    console.log('\n🧪 Test 5: Time Requirement Failure');
+    demonstrateValidationError(4, 'time condition not met');
+    
+    // Test 6: Out of bounds choice
+    console.log('\n🧪 Test 6: Out of Bounds Choice');
+    try {
+      engine.makeChoice(99);
+    } catch (error) {
+      console.log(`🚫 Navigation error: ${error.message}`);
+    }
+    
+    // Test 7: Add custom validation rule
+    console.log('\n🧪 Test 7: Custom Validation Rule');
+    const validator = engine.getChoiceValidator();
+    validator.addRule({
+      name: 'weather-safety',
+      priority: 10,
+      validate: (choice, context) => {
+        if (choice.text.includes('outside') && !context.state.flags.hasUmbrella) {
+          return {
+            isValid: false,
+            reason: 'Too dangerous to go outside without an umbrella!',
+            failedConditions: ['no-umbrella'],
+            suggestedChoices: context.currentNode.choices.filter(c => !c.text.includes('outside'))
+          };
+        }
+        return { isValid: true };
+      }
+    });
+    
+    // This should now fail our custom rule
+    console.log('Added custom weather-safety validation rule...');
+    demonstrateValidationError(2, 'custom weather rule failure');
+    
+    // Test 8: Show successful path with proper flags
+    console.log('\n🧪 Test 8: Successful Path with Flags');
+    
+    // Set up proper flags for success
+    const state = engine.getState();
+    state.flags.hasGoldenKey = true;
+    state.flags.inventory = { gold: 100, reputation: 10 };
+    
+    console.log('Set hasGoldenKey=true and sufficient inventory...');
+    displayCurrentState();
+    
+    console.log('Now attempting choice 2 (Use the golden key)...');
+    engine.makeChoice(1); // This should work now
+    displayCurrentState();
+    
+    console.log('\n✅ Demo completed successfully!');
+    console.log('\nKey takeaways:');
+    console.log('- ChoiceValidationError provides rich error information');
+    console.log('- Multiple validation rules can be applied in priority order');
+    console.log('- Custom validation rules can be added for game-specific logic');
+    console.log('- Flag, inventory, time, and enabled state validation work seamlessly');
+    console.log('- Error messages are both user-friendly and developer-friendly');
+    
+  } catch (error) {
+    console.error('Demo failed:', error);
+    process.exit(1);
+  }
+}
+
+// Run the demo
+runDemo();