@lifeonlars/prime-yggdrasil 0.3.0 → 0.4.0

package/cli/rules/interaction-patterns/focus-management.js

@@ -0,0 +1,187 @@
+/**
+ * Interaction Patterns Rule: Focus Management
+ *
+ * Validates proper focus management in Dialogs, Modals, and form flows.
+ * Ensures keyboard navigation works correctly and focus is trapped/returned appropriately.
+ *
+ * Phase 6 - Interaction Patterns Agent
+ */
+
+export default {
+  name: 'interaction-patterns/focus-management',
+  description: 'Validate Dialog/Modal focus patterns and keyboard navigation',
+  category: 'interaction-patterns',
+  severity: 'warning',
+  documentation: 'https://github.com/lifeonlars/prime-yggdrasil/blob/master/.ai/agents/interaction-patterns.md#5-focus-management',
+
+  validate(fileContent, filePath) {
+    const violations = [];
+
+    // Skip non-React/TSX files
+    if (!filePath.match(/\.(jsx|tsx|js|ts)$/)) {
+      return violations;
+    }
+
+    // Pattern 1: Check Dialog components for focus management
+    const dialogRegex = /<Dialog[^>]*>/g;
+    let match;
+
+    while ((match = dialogRegex.exec(fileContent)) !== null) {
+      const dialogStart = match.index;
+      const dialogEnd = fileContent.indexOf('</Dialog>', dialogStart);
+
+      if (dialogEnd === -1) continue;
+
+      const dialogContent = fileContent.substring(dialogStart, dialogEnd);
+      const line = this.getLineNumber(fileContent, dialogStart);
+
+      // Check 1: Dialog should have modal prop (focus trap)
+      if (!dialogContent.includes('modal')) {
+        violations.push({
+          line,
+          column: 1,
+          message: 'Dialog missing modal prop. Add modal={true} to trap focus within dialog.',
+          severity: 'warning',
+          rule: this.name,
+          suggestion: '<Dialog visible={visible} onHide={onHide} modal>',
+        });
+      }
+
+      // Check 2: First interactive element should have autoFocus
+      const hasAutoFocus = /autoFocus/.test(dialogContent);
+      const hasInteractiveElement = /(<InputText|<Button|<Dropdown|<Calendar|<Checkbox)/.test(dialogContent);
+
+      if (hasInteractiveElement && !hasAutoFocus) {
+        violations.push({
+          line,
+          column: 1,
+          message: 'Dialog first interactive element should have autoFocus for keyboard navigation.',
+          severity: 'info',
+          rule: this.name,
+          suggestion: '<InputText autoFocus /> // First field in dialog',
+        });
+      }
+
+      // Check 3: Dialog should have onHide handler (ESC key support)
+      if (!dialogContent.includes('onHide')) {
+        violations.push({
+          line,
+          column: 1,
+          message: 'Dialog missing onHide handler. Required for ESC key support.',
+          severity: 'error',
+          rule: this.name,
+          suggestion: '<Dialog visible={visible} onHide={() => setVisible(false)}>',
+        });
+      }
+    }
+
+    // Pattern 2: Check for interactive divs without keyboard handlers
+    const interactiveDivRegex = /<div[^>]*onClick[^>]*>/g;
+
+    while ((match = interactiveDivRegex.exec(fileContent)) !== null) {
+      const divTag = match[0];
+      const line = this.getLineNumber(fileContent, match.index);
+
+      // Check if div has keyboard handlers
+      const hasKeyboard = divTag.includes('onKeyDown') || divTag.includes('onKeyPress');
+      const hasRole = divTag.includes('role="button"') || divTag.includes('role=\\"button\\"');
+      const hasTabIndex = divTag.includes('tabIndex');
+
+      if (!hasKeyboard || !hasRole || !hasTabIndex) {
+        violations.push({
+          line,
+          column: 1,
+          message: 'Interactive div must have role="button", tabIndex, and keyboard handlers (onKeyDown).',
+          severity: 'error',
+          rule: this.name,
+          suggestion: this.getKeyboardHandlerSuggestion(),
+        });
+      }
+    }
+
+    // Pattern 3: Check form fields for logical tab order
+    const formRegex = /<form[^>]*>/g;
+
+    while ((match = formRegex.exec(fileContent)) !== null) {
+      const formStart = match.index;
+      const formEnd = fileContent.indexOf('</form>', formStart);
+
+      if (formEnd === -1) continue;
+
+      const formContent = fileContent.substring(formStart, formEnd);
+      const line = this.getLineNumber(fileContent, formStart);
+
+      // Check for explicit tabIndex that might break natural order
+      const explicitTabIndex = /tabIndex=\{?(\d+)\}?/.exec(formContent);
+
+      if (explicitTabIndex && parseInt(explicitTabIndex[1]) > 0) {
+        violations.push({
+          line: line + this.getLineNumber(formContent, explicitTabIndex.index),
+          column: 1,
+          message: 'Avoid positive tabIndex values. Use natural DOM order or tabIndex={0} for custom elements.',
+          severity: 'warning',
+          rule: this.name,
+          suggestion: 'Remove tabIndex or use tabIndex={0} for same-level focus order.',
+        });
+      }
+    }
+
+    // Pattern 4: Check for custom focus styles
+    const hasFocusStyles = /:focus/.test(fileContent) || /focus-visible/.test(fileContent);
+    const hasInteractiveComponents = /<(Button|InputText|Dropdown|Calendar)/.test(fileContent);
+
+    if (hasInteractiveComponents && fileContent.includes('outline: none') && !hasFocusStyles) {
+      const line = this.getLineNumber(fileContent, fileContent.indexOf('outline: none'));
+
+      violations.push({
+        line,
+        column: 1,
+        message: 'Removing outline without custom focus styles breaks keyboard navigation visibility.',
+        severity: 'error',
+        rule: this.name,
+        suggestion: 'Replace with: boxShadow: "0 0 0 2px var(--border-state-focus)"',
+      });
+    }
+
+    return violations;
+  },
+
+  getKeyboardHandlerSuggestion() {
+    return `
+<div
+  role="button"
+  tabIndex={0}
+  onClick={handleClick}
+  onKeyDown={e => (e.key === 'Enter' || e.key === ' ') && handleClick()}
+>
+  Click me
+</div>`;
+  },
+
+  getLineNumber(content, index) {
+    return content.substring(0, index).split('\n').length;
+  },
+
+  autofix(fileContent, violation) {
+    if (violation.message.includes('Dialog missing modal prop')) {
+      const dialogRegex = /<Dialog([^>]*)>/;
+      const match = dialogRegex.exec(fileContent);
+
+      if (match) {
+        const dialogTag = match[0];
+        const fixedTag = dialogTag.replace('<Dialog', '<Dialog modal');
+
+        return {
+          fixed: true,
+          content: fileContent.replace(dialogTag, fixedTag),
+          message: 'Added modal prop to Dialog',
+        };
+      }
+    }
+
+    return {
+      fixed: false,
+      message: 'Manual fix required. See suggestion in violation message.',
+    };
+  },
+};

package/cli/rules/interaction-patterns/generic-copy.js

@@ -0,0 +1,190 @@
+/**
+ * Interaction Patterns Rule: Generic Copy
+ *
+ * Enforces specific, action-oriented button labels and copy instead of generic terms.
+ * Aligns with AESTHETICS.md: "Be specific, be concise, be functional"
+ *
+ * Phase 6 - Interaction Patterns Agent
+ */
+
+export default {
+  name: 'interaction-patterns/generic-copy',
+  description: 'Enforce specific button labels over generic ones ("Save Changes" not "Submit")',
+  category: 'interaction-patterns',
+  severity: 'warning',
+  documentation: 'https://github.com/lifeonlars/prime-yggdrasil/blob/master/.ai/agents/interaction-patterns.md#7-copy-tone--content',
+
+  // Generic terms to avoid
+  genericTerms: {
+    // Button labels
+    'Submit': 'Use specific action like "Save Changes", "Create Account", "Send Message"',
+    'OK': 'Use specific action like "Confirm Delete", "Apply Settings", "Close"',
+    'Cancel': 'OK in most cases, but consider "Keep Editing", "Go Back" for clarity',
+    'Continue': 'Use specific action like "Next: Payment", "Proceed to Checkout"',
+    'Done': 'Use specific action like "Finish Setup", "Complete"',
+    'Click here': 'Use descriptive link text like "View documentation", "Learn more about tokens"',
+    'Click': 'Avoid instructional copy - buttons are self-evident',
+
+    // Messages
+    'Success!': 'Be specific: "Settings saved", "User created", "Email sent"',
+    'Error': 'Explain what failed: "Unable to save. Try again.", "Connection failed."',
+    'Warning': 'Be specific about the warning: "Unsaved changes will be lost"',
+    'Oops!': 'Avoid casual tone - be clear and pragmatic',
+    'Something went wrong': 'Explain the issue: "Unable to connect to server", "Invalid format"',
+    'Loading...': 'Be specific: "Loading users...", "Saving changes...", "Processing..."',
+  },
+
+  validate(fileContent, filePath) {
+    const violations = [];
+
+    // Skip non-React/TSX files
+    if (!filePath.match(/\.(jsx|tsx|js|ts)$/)) {
+      return violations;
+    }
+
+    // Pattern 1: Check Button component labels
+    const buttonLabelRegex = /<Button[^>]*label=["']([^"']+)["']/g;
+    let match;
+
+    while ((match = buttonLabelRegex.exec(fileContent)) !== null) {
+      const label = match[1];
+      const line = this.getLineNumber(fileContent, match.index);
+
+      if (this.genericTerms[label]) {
+        violations.push({
+          line,
+          column: 1,
+          message: `Generic button label "${label}". ${this.genericTerms[label]}`,
+          severity: 'warning',
+          rule: this.name,
+          suggestion: this.getSuggestion(label),
+        });
+      }
+    }
+
+    // Pattern 2: Check button element text content
+    const buttonTextRegex = /<button[^>]*>([^<]+)<\/button>/gi;
+
+    while ((match = buttonTextRegex.exec(fileContent)) !== null) {
+      const text = match[1].trim();
+      const line = this.getLineNumber(fileContent, match.index);
+
+      if (this.genericTerms[text]) {
+        violations.push({
+          line,
+          column: 1,
+          message: `Generic button text "${text}". ${this.genericTerms[text]}`,
+          severity: 'warning',
+          rule: this.name,
+          suggestion: this.getSuggestion(text),
+        });
+      }
+    }
+
+    // Pattern 3: Check Message/Toast content
+    const messagePatterns = [
+      /severity=["']success["'][^>]*text=["']([^"']+)["']/g,
+      /severity=["']error["'][^>]*text=["']([^"']+)["']/g,
+      /severity=["']warn["'][^>]*text=["']([^"']+)["']/g,
+      /summary=["']([^"']+)["']/g,
+    ];
+
+    messagePatterns.forEach(pattern => {
+      while ((match = pattern.exec(fileContent)) !== null) {
+        const text = match[1];
+        const line = this.getLineNumber(fileContent, match.index);
+
+        if (this.genericTerms[text]) {
+          violations.push({
+            line,
+            column: 1,
+            message: `Generic message "${text}". ${this.genericTerms[text]}`,
+            severity: 'warning',
+            rule: this.name,
+            suggestion: this.getSuggestion(text),
+          });
+        }
+
+        // Check for emoji/fluffy language
+        if (/[🎉😅❤️👍✨]/.test(text)) {
+          violations.push({
+            line,
+            column: 1,
+            message: `Avoid emoji in UI copy. Keep tone clear and pragmatic.`,
+            severity: 'warning',
+            rule: this.name,
+            suggestion: `Remove emoji from: "${text}"`,
+          });
+        }
+
+        // Check for casual/marketing language
+        const casualPhrases = [
+          /let's/i,
+          /awesome/i,
+          /amazing/i,
+          /yay/i,
+          /congrats/i,
+          /you're all set/i,
+        ];
+
+        casualPhrases.forEach(phrase => {
+          if (phrase.test(text)) {
+            violations.push({
+              line,
+              column: 1,
+              message: `Avoid casual/marketing language in UI copy: "${text}"`,
+              severity: 'warning',
+              rule: this.name,
+              suggestion: 'Use clear, functional copy. See docs/AESTHETICS.md for examples.',
+            });
+          }
+        });
+      }
+    });
+
+    // Pattern 4: Check link text
+    const linkTextRegex = /<a[^>]*>([^<]+)<\/a>/gi;
+
+    while ((match = linkTextRegex.exec(fileContent)) !== null) {
+      const text = match[1].trim();
+      const line = this.getLineNumber(fileContent, match.index);
+
+      if (this.genericTerms[text]) {
+        violations.push({
+          line,
+          column: 1,
+          message: `Generic link text "${text}". ${this.genericTerms[text]}`,
+          severity: 'warning',
+          rule: this.name,
+          suggestion: 'Use descriptive link text that explains the destination.',
+        });
+      }
+    }
+
+    return violations;
+  },
+
+  getSuggestion(genericTerm) {
+    const examples = {
+      'Submit': 'Examples: "Save Changes", "Create Project", "Send Email"',
+      'OK': 'Examples: "Confirm", "Apply", "Close Dialog"',
+      'Continue': 'Examples: "Next: Payment", "Proceed to Review"',
+      'Success!': 'Examples: "Settings saved", "User created successfully"',
+      'Error': 'Examples: "Unable to save. Try again.", "Invalid email format."',
+    };
+
+    return examples[genericTerm] || 'Use specific, action-oriented copy.';
+  },
+
+  getLineNumber(content, index) {
+    return content.substring(0, index).split('\n').length;
+  },
+
+  autofix(fileContent, violation) {
+    // No automatic fix for copy - requires human judgment
+    return {
+      fixed: false,
+      message: 'Manual fix required. Replace generic copy with specific, action-oriented text.',
+    };
+  },
+};

package/cli/rules/interaction-patterns/index.js

@@ -0,0 +1,17 @@
+/**
+ * Interaction Patterns Rules
+ *
+ * Phase 6 - Behavioral consistency enforcement
+ *
+ * All rules enforce patterns from .ai/agents/interaction-patterns.md
+ */
+
+import stateCompleteness from './state-completeness.js';
+import genericCopy from './generic-copy.js';
+import focusManagement from './focus-management.js';
+
+export default {
+  'interaction-patterns/state-completeness': stateCompleteness,
+  'interaction-patterns/generic-copy': genericCopy,
+  'interaction-patterns/focus-management': focusManagement,
+};

package/cli/rules/interaction-patterns/state-completeness.js

@@ -0,0 +1,194 @@
+/**
+ * Interaction Patterns Rule: State Completeness
+ *
+ * Enforces that async operations and data-driven components handle all required states:
+ * - Loading state
+ * - Error state
+ * - Empty state
+ * - Disabled state (when applicable)
+ *
+ * Phase 6 - Interaction Patterns Agent
+ */
+
+export default {
+  name: 'interaction-patterns/state-completeness',
+  description: 'Enforce state completeness (loading/error/empty/disabled) for async operations',
+  category: 'interaction-patterns',
+  severity: 'warning',
+  documentation: 'https://github.com/lifeonlars/prime-yggdrasil/blob/master/.ai/agents/interaction-patterns.md#1-state-management-patterns',
+
+  validate(fileContent, filePath) {
+    const violations = [];
+
+    // Skip non-React/TSX files
+    if (!filePath.match(/\.(jsx|tsx|js|ts)$/)) {
+      return violations;
+    }
+
+    // Pattern 1: Detect async operations (useEffect, fetch, axios, async functions)
+    const asyncPatterns = [
+      /useEffect\s*\(/g,
+      /async\s+function/g,
+      /async\s+\(/g,
+      /\.then\s*\(/g,
+      /await\s+fetch/g,
+      /await\s+axios/g,
+    ];
+
+    const hasAsyncOperation = asyncPatterns.some(pattern => pattern.test(fileContent));
+
+    if (!hasAsyncOperation) {
+      // No async operations, skip validation
+      return violations;
+    }
+
+    // Pattern 2: Check for state variables that suggest data loading
+    const statePatterns = {
+      loading: /const\s+\[\s*\w*loading\w*\s*,/gi,
+      error: /const\s+\[\s*\w*error\w*\s*,/gi,
+      data: /const\s+\[\s*\w*(data|items|users|records)\w*\s*,/gi,
+    };
+
+    const hasLoadingState = statePatterns.loading.test(fileContent);
+    const hasErrorState = statePatterns.error.test(fileContent);
+    const hasDataState = statePatterns.data.test(fileContent);
+
+    // Pattern 3: Detect DataTable, List, or other data-driven components
+    const dataComponents = [
+      'DataTable',
+      'DataView',
+      'Tree',
+      'TreeTable',
+      'OrderList',
+      'PickList',
+    ];
+
+    const hasDataComponent = dataComponents.some(component =>
+      fileContent.includes(`<${component}`)
+    );
+
+    // Violation detection
+    if (hasAsyncOperation || hasDataComponent) {
+      const missingStates = [];
+
+      if (!hasLoadingState) {
+        missingStates.push('loading');
+      }
+
+      if (!hasErrorState) {
+        missingStates.push('error');
+      }
+
+      // Check for empty state handling (conditional rendering when data is empty)
+      const hasEmptyCheck = /\.length\s*===\s*0/.test(fileContent) ||
+                           /\.length\s*<\s*1/.test(fileContent) ||
+                           /!.*\.length/.test(fileContent);
+
+      if (hasDataState && !hasEmptyCheck) {
+        missingStates.push('empty');
+      }
+
+      if (missingStates.length > 0) {
+        violations.push({
+          line: 1, // Could be improved with AST parsing for exact line
+          column: 1,
+          message: `Missing state handling: ${missingStates.join(', ')}`,
+          severity: 'warning',
+          rule: this.name,
+          suggestion: this.getSuggestion(missingStates),
+        });
+      }
+    }
+
+    // Pattern 4: Check for proper conditional rendering of states
+    if (hasLoadingState) {
+      const hasLoadingRender = fileContent.includes('loading') &&
+                               (fileContent.includes('ProgressSpinner') ||
+                                fileContent.includes('Skeleton') ||
+                                fileContent.includes('loading={'));
+
+      if (!hasLoadingRender) {
+        violations.push({
+          line: 1,
+          column: 1,
+          message: 'Loading state defined but not rendered. Add <ProgressSpinner /> or loading indicator.',
+          severity: 'warning',
+          rule: this.name,
+          suggestion: 'if (loading) return <ProgressSpinner />;',
+        });
+      }
+    }
+
+    if (hasErrorState) {
+      const hasErrorRender = fileContent.includes('error') &&
+                            (fileContent.includes('Message') ||
+                             fileContent.includes('InlineMessage') ||
+                             fileContent.includes('Toast'));
+
+      if (!hasErrorRender) {
+        violations.push({
+          line: 1,
+          column: 1,
+          message: 'Error state defined but not rendered. Add <Message severity="error" /> or error display.',
+          severity: 'warning',
+          rule: this.name,
+          suggestion: 'if (error) return <Message severity="error" text="Unable to load data. Try again." />;',
+        });
+      }
+    }
+
+    return violations;
+  },
+
+  getSuggestion(missingStates) {
+    const suggestions = {
+      loading: 'Add: const [loading, setLoading] = useState(false);',
+      error: 'Add: const [error, setError] = useState(null);',
+      empty: 'Add empty state check: if (data.length === 0) return <EmptyState />;',
+    };
+
+    return missingStates.map(state => suggestions[state]).join('\n');
+  },
+
+  autofix(fileContent, violation) {
+    // Basic autofix: Add state variable declarations at the beginning of the component
+
+    if (violation.message.includes('Missing state handling')) {
+      const missingStates = violation.message.match(/: (.+)$/)[1].split(', ');
+
+      let additions = [];
+
+      if (missingStates.includes('loading')) {
+        additions.push("const [loading, setLoading] = useState(false);");
+      }
+
+      if (missingStates.includes('error')) {
+        additions.push("const [error, setError] = useState(null);");
+      }
+
+      // Find the first function component or class component
+      const componentMatch = fileContent.match(/(function|const)\s+\w+.*\{/);
+
+      if (componentMatch) {
+        const insertPosition = componentMatch.index + componentMatch[0].length;
+        const indentation = '  ';
+
+        const fixedContent =
+          fileContent.slice(0, insertPosition) +
+          '\n' + additions.map(line => indentation + line).join('\n') +
+          fileContent.slice(insertPosition);
+
+        return {
+          fixed: true,
+          content: fixedContent,
+          message: `Added missing state declarations: ${missingStates.join(', ')}`,
+        };
+      }
+    }
+
+    return {
+      fixed: false,
+      message: 'Manual fix required. See suggestion in violation message.',
+    };
+  },
+};

package/docs/AESTHETICS.md

@@ -94,9 +94,9 @@ Agents must ensure all guidance, validation, and generated code consistently fol
 
 **Drift Validator** — Detect violations of architectural rules. Flag custom components that duplicate PrimeReact. Validate token-first approach.
 
-**Interaction Patterns** *(future)* — Enforce state visibility. Standardize empty/loading/error patterns. Specify keyboard + focus behavior. Ensure copy is clear and pragmatic.
+**Interaction Patterns** *(Phase 6 - Active ✅)* — Enforce state completeness (loading/error/empty/disabled). Detect generic copy. Validate focus management and keyboard navigation. Ensure copy is clear and pragmatic.
 
-**Accessibility** *(future)* — Validate WCAG 2.1 AA compliance. Check contrast ratios. Ensure color is not the only cue. Verify keyboard navigation.
+**Accessibility** *(Phase 6 - Active ✅)* — Validate WCAG 2.1 AA compliance. Check alt text and form labels. Verify contrast ratios. Ensure color is not the only cue. Validate ARIA and keyboard navigation.
 
 ### Quick reference for agents
 
@@ -164,5 +164,5 @@ Button labels: Specific actions ("Save Changes", "Delete Item"), not generic ("O
 
 ---
 
-**Status:** Mandatory reference for all agents
-**Last updated:** 2026-01-10
+**Status:** Mandatory reference for all agents (6/6 active - Phase 6 complete ✅)
+**Last updated:** 2026-01-11