@fr0mpy/component-system 2.1.0 → 2.2.0

package/bin/cli.js

@@ -52,25 +52,37 @@ function copySubdir(subdir) {
   return true;
 }
 
-function injectStylingTrigger() {
+function injectTriggers() {
   const triggersDDir = path.join(TARGET_DIR, 'hooks', 'triggers.d');
-  const stylingTriggerSrc = path.join(TEMPLATES_DIR, 'hooks', 'triggers.d', 'styling.json');
-  const stylingTriggerDest = path.join(triggersDDir, 'styling.json');
+  if (!fs.existsSync(triggersDDir)) return false;
 
-  if (fs.existsSync(triggersDDir) && fs.existsSync(stylingTriggerSrc)) {
-    fs.copyFileSync(stylingTriggerSrc, stylingTriggerDest);
-    return true;
+  const triggers = ['styling.json', 'react-patterns.json'];
+  let injected = false;
+
+  for (const trigger of triggers) {
+    const src = path.join(TEMPLATES_DIR, 'hooks', 'triggers.d', trigger);
+    const dest = path.join(triggersDDir, trigger);
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, dest);
+      injected = true;
+    }
   }
-  return false;
+  return injected;
 }
 
-function removeStylingTrigger() {
-  const stylingTrigger = path.join(TARGET_DIR, 'hooks', 'triggers.d', 'styling.json');
-  if (fs.existsSync(stylingTrigger)) {
-    fs.unlinkSync(stylingTrigger);
-    return true;
+function removeTriggers() {
+  const triggersDDir = path.join(TARGET_DIR, 'hooks', 'triggers.d');
+  const triggers = ['styling.json', 'react-patterns.json'];
+  let removed = false;
+
+  for (const trigger of triggers) {
+    const triggerPath = path.join(triggersDDir, trigger);
+    if (fs.existsSync(triggerPath)) {
+      fs.unlinkSync(triggerPath);
+      removed = true;
+    }
   }
-  return false;
+  return removed;
 }
 
 async function init() {
@@ -129,11 +141,11 @@ async function init() {
   console.log('   📄 commands/setup-styling.md');
   console.log('   📄 commands/component-harness.md\n');
 
-  // Inject styling trigger if prompt-system is installed
+  // Inject triggers if prompt-system is installed
   if (promptSystemExists) {
-    if (injectStylingTrigger()) {
-      console.log('✅ Injected styling trigger into prompt system.');
-      console.log('   Styling-related prompts will now auto-trigger the styling skill.\n');
+    if (injectTriggers()) {
+      console.log('✅ Injected triggers into prompt system.');
+      console.log('   Styling and React patterns will auto-trigger on relevant prompts.\n');
     }
   } else {
     console.log('ℹ️  Prompt system not detected.');
@@ -207,8 +219,8 @@ function remove() {
     }
   }
 
-  // Remove styling trigger
-  removeStylingTrigger();
+  // Remove triggers
+  removeTriggers();
 
   // Remove styling-config.json if it exists
   const stylingConfig = path.join(TARGET_DIR, 'styling-config.json');

package/bin/validate-harness.js

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+
+/**
+ * Validate and track component harness completeness.
+ * Keeps the design agent on track by reporting missing components.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const CLAUDE_DIR = path.join(process.cwd(), '.claude');
+const RECIPES_DIR = path.join(CLAUDE_DIR, 'component-recipes');
+const HARNESS_DIR = path.join(process.cwd(), 'component-harness');
+const COMPONENTS_DIR = path.join(HARNESS_DIR, 'src', 'components');
+
+function getRecipeNames() {
+  if (!fs.existsSync(RECIPES_DIR)) return [];
+  return fs.readdirSync(RECIPES_DIR)
+    .filter(f => f.endsWith('.md'))
+    .map(f => f.replace('.md', ''));
+}
+
+function getGeneratedComponents() {
+  if (!fs.existsSync(COMPONENTS_DIR)) return [];
+  return fs.readdirSync(COMPONENTS_DIR)
+    .filter(f => f.endsWith('.tsx') && f !== 'index.ts')
+    .map(f => f.replace('.tsx', '').toLowerCase());
+}
+
+function toComponentName(recipe) {
+  // kebab-case to PascalCase
+  return recipe.split('-').map(s => s.charAt(0).toUpperCase() + s.slice(1)).join('');
+}
+
+function validate() {
+  console.log('Component Harness Validation\n');
+  console.log('='.repeat(40) + '\n');
+
+  // Check prerequisites
+  if (!fs.existsSync(CLAUDE_DIR)) {
+    console.log('❌ .claude/ directory not found');
+    console.log('   Run: npx @fr0mpy/component-system\n');
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(RECIPES_DIR)) {
+    console.log('❌ No component recipes found');
+    console.log('   Run: /setup-styling\n');
+    process.exit(1);
+  }
+
+  const recipes = getRecipeNames();
+  const generated = getGeneratedComponents();
+
+  console.log(`Recipes:    ${recipes.length}`);
+  console.log(`Generated:  ${generated.length}\n`);
+
+  // Find missing
+  const missing = [];
+  const present = [];
+
+  for (const recipe of recipes) {
+    const componentName = toComponentName(recipe);
+    const exists = generated.some(g =>
+      g.toLowerCase() === recipe.toLowerCase() ||
+      g.toLowerCase() === componentName.toLowerCase()
+    );
+
+    if (exists) {
+      present.push({ recipe, component: componentName });
+    } else {
+      missing.push({ recipe, component: componentName });
+    }
+  }
+
+  // Report
+  if (missing.length === 0) {
+    console.log('✅ All components generated!\n');
+  } else {
+    console.log(`⚠️  Missing ${missing.length} components:\n`);
+    missing.forEach(({ recipe, component }) => {
+      console.log(`   [ ] ${component} (from ${recipe}.md)`);
+    });
+    console.log('');
+  }
+
+  // Check Gallery.tsx imports
+  const galleryPath = path.join(HARNESS_DIR, 'src', 'Gallery.tsx');
+  if (fs.existsSync(galleryPath)) {
+    const galleryContent = fs.readFileSync(galleryPath, 'utf-8');
+    const importedComponents = [];
+
+    for (const { component } of present) {
+      if (galleryContent.includes(component)) {
+        importedComponents.push(component);
+      }
+    }
+
+    const notInGallery = present.filter(p => !importedComponents.includes(p.component));
+
+    if (notInGallery.length > 0) {
+      console.log(`⚠️  ${notInGallery.length} components not in Gallery.tsx:\n`);
+      notInGallery.forEach(({ component }) => {
+        console.log(`   [ ] ${component}`);
+      });
+      console.log('');
+    }
+  }
+
+  // Summary
+  const pct = Math.round((present.length / recipes.length) * 100);
+  console.log('='.repeat(40));
+  console.log(`Progress: ${present.length}/${recipes.length} (${pct}%)\n`);
+
+  // Output for agent consumption
+  if (missing.length > 0) {
+    console.log('NEXT_ACTION: Generate missing components:');
+    console.log(missing.slice(0, 5).map(m => m.component).join(', '));
+    if (missing.length > 5) {
+      console.log(`... and ${missing.length - 5} more`);
+    }
+    console.log('');
+  }
+
+  return { recipes, present, missing, total: recipes.length };
+}
+
+function generateStubs() {
+  const { missing } = validate();
+
+  if (missing.length === 0) {
+    console.log('No stubs needed - all components exist.\n');
+    return;
+  }
+
+  console.log('\nGenerating stubs for missing components...\n');
+
+  fs.mkdirSync(COMPONENTS_DIR, { recursive: true });
+
+  for (const { recipe, component } of missing) {
+    const stubPath = path.join(COMPONENTS_DIR, `${component}.tsx`);
+    const stub = `// TODO: Generate from recipe: ${recipe}.md
+import * as React from "react"
+
+export interface ${component}Props {
+  children?: React.ReactNode
+  className?: string
+}
+
+export const ${component} = React.forwardRef<HTMLDivElement, ${component}Props>(
+  ({ children, className, ...props }, ref) => {
+    return (
+      <div ref={ref} className={className} {...props}>
+        {/* TODO: Implement ${component} from .claude/component-recipes/${recipe}.md */}
+        <span className="text-yellow-500">[${component} - Not Implemented]</span>
+        {children}
+      </div>
+    )
+  }
+)
+${component}.displayName = "${component}"
+`;
+
+    fs.writeFileSync(stubPath, stub);
+    console.log(`   ✓ ${component}.tsx (stub)`);
+  }
+
+  console.log('\nStubs created. Run validation again to update Gallery.tsx\n');
+}
+
+function updateIndex() {
+  if (!fs.existsSync(COMPONENTS_DIR)) {
+    console.log('❌ Components directory not found\n');
+    return;
+  }
+
+  const components = fs.readdirSync(COMPONENTS_DIR)
+    .filter(f => f.endsWith('.tsx'))
+    .map(f => f.replace('.tsx', ''));
+
+  const exports = components
+    .map(c => `export * from "./${c}"`)
+    .join('\n');
+
+  const indexPath = path.join(COMPONENTS_DIR, 'index.ts');
+  fs.writeFileSync(indexPath, exports + '\n');
+
+  console.log(`✅ Updated index.ts with ${components.length} exports\n`);
+}
+
+// CLI
+const command = process.argv[2];
+
+switch (command) {
+  case 'stubs':
+    generateStubs();
+    break;
+  case 'index':
+    updateIndex();
+    break;
+  case 'help':
+    console.log(`
+validate-harness - Component harness validation tool
+
+Usage:
+  npx validate-harness           Validate component completeness
+  npx validate-harness stubs     Generate stub files for missing components
+  npx validate-harness index     Update components/index.ts exports
+
+Run from project root (where .claude/ exists).
+`);
+    break;
+  default:
+    validate();
+}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@fr0mpy/component-system",
-  "version": "2.1.0",
-  "description": "Claude Code UI styling system with design tokens, 36 component recipes, and visual harness",
+  "version": "2.2.0",
+  "description": "Claude Code UI styling system with design tokens, 40 Base UI component recipes, and visual harness",
   "main": "index.js",
   "bin": {
-    "fromp-component-system": "./bin/cli.js"
+    "component-system": "./bin/cli.js",
+    "validate-harness": "./bin/validate-harness.js"
   },
   "scripts": {
     "test": "echo \"Tests not yet configured\""

package/templates/hooks/triggers.d/react-patterns.json

@@ -0,0 +1,18 @@
+{
+  "react-patterns": [
+    "react",
+    "component",
+    "useState",
+    "useEffect",
+    "useCallback",
+    "useMemo",
+    "useRef",
+    "useContext",
+    "hooks",
+    "render",
+    "gallery",
+    "harness",
+    "demo",
+    "showcase"
+  ]
+}

package/templates/skills/react-patterns.md

@@ -0,0 +1,137 @@
+# React Patterns
+
+Apply when creating, modifying, or reviewing React components.
+
+## Rules of Hooks (CRITICAL)
+
+Hooks must be called in the **same order** every render. Violating this crashes the app.
+
+### Never Do
+
+```tsx
+// ❌ Hook in callback/render prop
+const demos = [{
+  render: () => {
+    const [state, setState] = useState()  // CRASHES
+    return <Component />
+  }
+}]
+
+// ❌ Hook after conditional return
+if (loading) return <Spinner />
+const [data, setData] = useState()  // CRASHES
+
+// ❌ Hook in condition
+if (userId) {
+  const [user, setUser] = useState()  // CRASHES
+}
+
+// ❌ Hook in loop
+items.map(item => {
+  const [selected, setSelected] = useState()  // CRASHES
+})
+```
+
+### Always Do
+
+```tsx
+// ✅ Extract to separate component
+const CheckboxDemo = () => {
+  const [checked, setChecked] = useState(false)
+  return <Checkbox checked={checked} onChange={setChecked} />
+}
+
+// ✅ Hooks before any returns
+const [data, setData] = useState()
+const [loading, setLoading] = useState(true)
+if (loading) return <Spinner />
+
+// ✅ Condition inside hook, not hook inside condition
+useEffect(() => {
+  if (userId) fetchUser(userId)
+}, [userId])
+```
+
+## State Updates
+
+```tsx
+// ❌ Stale state - only increments once
+setCount(count + 1)
+setCount(count + 1)
+
+// ✅ Functional update - increments twice
+setCount(prev => prev + 1)
+setCount(prev => prev + 1)
+```
+
+## Dependencies
+
+```tsx
+// ❌ Missing dependency - stale closure
+useEffect(() => {
+  doSomething(value)
+}, [])
+
+// ✅ All dependencies listed
+useEffect(() => {
+  doSomething(value)
+}, [value])
+```
+
+## Component Galleries
+
+When building component showcases:
+
+| Pattern | Wrong | Right |
+|---------|-------|-------|
+| Stateful demo | Hook in render prop | Separate `*Demo` component |
+| Context consumer | Render alone | Wrap in provider |
+| Controlled input | Internal state | Props from wrapper |
+
+```tsx
+// ❌ Wrong - hook in render function
+const components = [{
+  name: "Checkbox",
+  render: () => {
+    const [checked, setChecked] = useState(false)
+    return <Checkbox checked={checked} />
+  }
+}]
+
+// ✅ Right - separate component
+const CheckboxDemo = () => {
+  const [checked, setChecked] = useState(false)
+  return <Checkbox checked={checked} onChange={setChecked} />
+}
+
+const components = [{
+  name: "Checkbox",
+  render: () => <CheckboxDemo />
+}]
+```
+
+## Cleanup
+
+```tsx
+// ❌ Memory leak
+useEffect(() => {
+  const id = setInterval(tick, 1000)
+}, [])
+
+// ✅ Cleanup on unmount
+useEffect(() => {
+  const id = setInterval(tick, 1000)
+  return () => clearInterval(id)
+}, [])
+```
+
+## Checklist
+
+Before delivering React code:
+
+- [ ] No hooks in callbacks, loops, conditions, or render props
+- [ ] No hooks after conditional returns
+- [ ] All `useEffect`/`useCallback`/`useMemo` deps included
+- [ ] Functional state updates when depending on previous state
+- [ ] Context consumers wrapped in their providers
+- [ ] Effects return cleanup functions where needed