@schandlergarcia/sf-web-components 1.9.43 → 1.9.45

package/.a4drules/RULES.md

@@ -0,0 +1,456 @@
+# Project Rules for sf-web-components
+
+These rules are **MANDATORY** and must be followed by all contributors, including AI assistants.
+
+## Rule 1: Documentation is the Source of Truth
+
+**The `.a4drules/skills/component-library/` directory is the authoritative source for all component contracts.**
+
+- Code MUST match documentation, not the other way around
+- Never change component names without updating documentation FIRST
+- If documentation says `UIButton`, the file MUST be named `UIButton.tsx`
+- If you find a mismatch, the documentation is correct and the code is wrong
+
+### Verification
+```bash
+# Check if code matches docs
+bash scripts/verify-consistency.sh
+```
+
+---
+
+## Rule 2: CHANGELOG.md is Mandatory
+
+**EVERY change to this package MUST be documented in CHANGELOG.md BEFORE publishing.**
+
+### Required Changelog Entries
+
+#### For Component Changes
+```markdown
+### Added
+- UINewComponent.tsx - Description of what it does
+  - Props: list key props
+  - Usage example
+  - Documented in .a4drules/skills/component-library/xyz.md
+
+### Changed
+- UIButton.tsx - Description of what changed
+  - Migration: How to update code
+  - Breaking: Yes/No
+
+### Fixed
+- CRITICAL: Description of critical fix
+  - Issue: What was broken
+  - Cause: Why it was broken
+  - Fix: How it was fixed
+  - Affected versions: x.x.x - x.x.x
+```
+
+#### For Documentation Changes
+```markdown
+### Documentation
+- Updated .a4drules/skills/component-library/ui-primitives.md
+  - Added UINewComponent documentation
+  - Clarified UIButton props
+```
+
+#### For Breaking Changes
+```markdown
+### Breaking Changes
+⚠️ **ComponentName renamed from OldName to NewName**
+- Reason: Explanation
+- Migration:
+  \`\`\`tsx
+  // Before
+  import { OldName } from '@/components/library';
+  
+  // After
+  import { NewName } from '@/components/library';
+  \`\`\`
+```
+
+### When to Update CHANGELOG
+
+**Update CHANGELOG.md in the SAME commit as the change.**
+
+Do NOT:
+- ❌ Make changes and forget to update CHANGELOG
+- ❌ Update CHANGELOG in a separate commit
+- ❌ Publish without CHANGELOG entry
+
+Do:
+- ✅ Update CHANGELOG in same commit as code changes
+- ✅ Use clear, descriptive language
+- ✅ Include version number and date
+- ✅ Categorize changes (Added, Changed, Fixed, etc.)
+
+### Pre-Publish Checklist
+
+Before running `npm version` or `npm publish`:
+
+```bash
+# 1. Verify all changes are documented in CHANGELOG.md
+git diff HEAD src/ | grep -v "index" > /tmp/changes.diff
+echo "Have you documented all these changes in CHANGELOG.md?"
+cat /tmp/changes.diff
+
+# 2. Verify consistency
+bash scripts/verify-consistency.sh
+
+# 3. Verify build
+npm run build
+
+# 4. Check CHANGELOG has entry for current version
+VERSION=$(node -p "require('./package.json').version")
+grep -q "## \[$VERSION\]" CHANGELOG.md || echo "ERROR: No CHANGELOG entry for version $VERSION"
+```
+
+---
+
+## Rule 3: Component Naming Convention
+
+**Library components MUST use UI prefix to distinguish from shadcn components.**
+
+### Correct Names (src/components/library/ui/)
+```
+UIButton.tsx     ✅
+UIInput.tsx      ✅
+UIText.tsx       ✅
+UICard.tsx       ✅
+UIChip.tsx       ✅
+UIContainer.tsx  ✅
+UIToggle.tsx     ✅
+```
+
+### Incorrect Names (DO NOT USE)
+```
+Button.tsx       ❌ (Reserved for outer app shadcn)
+Input.tsx        ❌ (Reserved for outer app shadcn)
+Text.tsx         ❌ (Use UIText.tsx)
+Card.tsx         ❌ (Use UICard.tsx)
+```
+
+### Why This Matters
+
+From `.a4drules/skills/component-library/common-mistakes.md`:
+
+> "shadcn components (`Button`, `Card`, `Input`, `Select`, `Alert`, `Skeleton`, etc.) exist for the outer app only. In command center pages, use the equivalent library component (`UIButton`, `BaseCard`/`WidgetCard`, `UIInput`, `Select`, `Alert`, `Skeleton`, etc. from `@/components/library`)"
+
+**Shadcn naming = Outer application shell**
+**UI prefix = Command center library components**
+
+This distinction prevents naming collisions and makes it clear which components are for which purpose.
+
+---
+
+## Rule 4: Templates Must Match Documentation
+
+**Templates in `src/templates/` MUST import components using names from `.a4drules/skills/component-library/`.**
+
+### Correct Template Imports
+```tsx
+// ✅ CORRECT - Matches ui-primitives.md
+import UIButton from '@/components/library/ui/UIButton';
+import UIInput from '@/components/library/ui/UIInput';
+```
+
+### Incorrect Template Imports
+```tsx
+// ❌ WRONG - Does not match documentation
+import Button from '@/components/library/ui/Button';
+import Input from '@/components/library/ui/Input';
+```
+
+### Verification
+```bash
+# Check all templates for correct imports
+grep -r "from '@/components/library/ui/UIButton'" src/templates/
+grep -r "from '@/components/library/ui/UIInput'" src/templates/
+
+# Verify no incorrect imports exist
+! grep -r "from '@/components/library/ui/Button'" src/templates/
+! grep -r "from '@/components/library/ui/Input'" src/templates/
+```
+
+---
+
+## Rule 5: Never Publish Without Testing
+
+**Every version MUST be tested with the postinstall script before publishing.**
+
+### Test Process
+
+1. **Build the package**
+   ```bash
+   npm run build
+   ```
+
+2. **Pack the package**
+   ```bash
+   npm pack
+   # Creates schandlergarcia-sf-web-components-1.9.x.tgz
+   ```
+
+3. **Test in fresh directory**
+   ```bash
+   # Create test environment
+   mkdir -p /tmp/test-sf-components
+   cd /tmp/test-sf-components
+   
+   # Minimal package.json
+   cat > package.json << 'EOF'
+   {
+     "name": "test-project",
+     "version": "1.0.0",
+     "type": "module"
+   }
+   EOF
+   
+   # Install from tarball
+   npm install /path/to/schandlergarcia-sf-web-components-1.9.x.tgz
+   
+   # Verify files copied correctly
+   ls src/components/library/ui/UIButton.tsx || echo "ERROR: UIButton not copied"
+   ls src/components/library/ui/UIInput.tsx || echo "ERROR: UIInput not copied"
+   ls src/pages/NotFound.tsx || echo "ERROR: NotFound template not copied"
+   
+   # Verify imports in NotFound
+   grep "UIButton" src/pages/NotFound.tsx || echo "ERROR: NotFound doesn't import UIButton"
+   ```
+
+4. **Only publish if test passes**
+   ```bash
+   # If test passed, publish
+   npm publish
+   ```
+
+---
+
+## Rule 6: File Extensions Matter
+
+**Use TypeScript (.tsx) for all new components.**
+
+### Preferred Extensions
+```
+UIButton.tsx     ✅ TypeScript with JSX
+UIInput.tsx      ✅ TypeScript with JSX
+types.ts         ✅ TypeScript types
+```
+
+### Discouraged Extensions
+```
+Button.jsx       ❌ JavaScript (use TypeScript)
+utils.js         ❌ JavaScript (use TypeScript)
+```
+
+### When to Use .jsx
+Only when maintaining existing JavaScript components that haven't been migrated to TypeScript yet.
+
+---
+
+## Rule 7: Version Control for Critical Changes
+
+**Component renames, removals, or breaking API changes MUST be thoroughly documented.**
+
+### Required Information
+
+1. **What changed**
+   - Old name → New name
+   - Old API → New API
+
+2. **Why it changed**
+   - Reason for the change
+   - Problem being solved
+
+3. **How to migrate**
+   - Step-by-step instructions
+   - Code examples (before/after)
+
+4. **Affected versions**
+   - First broken version
+   - First fixed version
+
+5. **Testing evidence**
+   - Commands run to verify
+   - Output of verification scripts
+
+### Example Documentation
+
+```markdown
+## Component Rename: Button → UIButton
+
+### What Changed
+- File renamed: Button.jsx → UIButton.tsx
+- Import path: '@/components/library/ui/Button' → '@/components/library/ui/UIButton'
+- Export name: Button → UIButton
+
+### Why
+- Shadcn component names (Button, Input) are reserved for outer app
+- Library components need UI prefix for distinction
+- Documented requirement in .a4drules/skills/component-library/
+
+### Migration
+\`\`\`tsx
+// Before
+import { Button } from '@/components/library';
+
+// After
+import { UIButton } from '@/components/library';
+
+// Usage (unchanged)
+<UIButton variant="primary">Click Me</UIButton>
+\`\`\`
+
+### Affected Versions
+- Broken: v1.9.29 - v1.9.42
+- Fixed: v1.9.43
+
+### Verification
+\`\`\`bash
+bash scripts/verify-consistency.sh
+npm run build
+\`\`\`
+```
+
+---
+
+## Rule 8: AI Assistant Guidelines
+
+**When an AI assistant (like Claude) is working on this project:**
+
+### Must Do
+1. ✅ Read `.a4drules/skills/component-library/` before making any component changes
+2. ✅ Run `bash scripts/verify-consistency.sh` before suggesting changes
+3. ✅ Update CHANGELOG.md in the same commit as code changes
+4. ✅ Verify templates import components correctly
+5. ✅ Explain why a change matches the documented requirements
+
+### Must Not Do
+1. ❌ Rename components without checking documentation first
+2. ❌ Use shadcn names (Button, Input) in library/ui/
+3. ❌ Publish without updating CHANGELOG.md
+4. ❌ Skip verification scripts
+5. ❌ Make assumptions about naming conventions
+
+### If Uncertain
+1. Check `.a4drules/skills/component-library/ui-primitives.md`
+2. Check CHANGELOG.md for historical context
+3. Check golden version (v1.9.25-1.9.28) for reference
+4. Ask before making breaking changes
+
+---
+
+## Rule 9: Golden Version Reference
+
+**Versions 1.9.25-1.9.28 are the golden reference.**
+
+When in doubt about:
+- Component names
+- File structure
+- Import patterns
+- Documentation format
+
+Reference these versions:
+```bash
+# View golden version on npm
+npm view @schandlergarcia/sf-web-components@1.9.28
+
+# Check working example
+ls /Users/stephan.garcia/reactapp4/src/components/library/ui/
+```
+
+---
+
+## Rule 10: Pre-Commit Verification
+
+**Before every commit, verify consistency.**
+
+### Recommended Git Hook
+
+Create `.git/hooks/pre-commit`:
+```bash
+#!/bin/bash
+# Pre-commit hook to verify consistency
+
+echo "Running consistency checks..."
+
+# Check if verify script exists and run it
+if [ -f "scripts/verify-consistency.sh" ]; then
+  bash scripts/verify-consistency.sh
+  if [ $? -ne 0 ]; then
+    echo "❌ Consistency checks failed. Fix errors before committing."
+    exit 1
+  fi
+fi
+
+# Check if CHANGELOG was updated (for src/ changes)
+if git diff --cached --name-only | grep -q "^src/"; then
+  if ! git diff --cached --name-only | grep -q "CHANGELOG.md"; then
+    echo "⚠️  WARNING: You modified src/ but didn't update CHANGELOG.md"
+    echo "Please update CHANGELOG.md before committing."
+    exit 1
+  fi
+fi
+
+echo "✅ Pre-commit checks passed"
+exit 0
+```
+
+Make it executable:
+```bash
+chmod +x .git/hooks/pre-commit
+```
+
+---
+
+## Enforcement
+
+These rules are **mandatory**, not suggestions.
+
+**Violations will result in:**
+- ❌ Broken consuming applications
+- ❌ Difficult-to-debug import errors
+- ❌ Lost development time
+- ❌ Frustrated users
+
+**Following these rules ensures:**
+- ✅ Consistent, predictable behavior
+- ✅ Easy debugging and maintenance
+- ✅ Clear documentation trail
+- ✅ Smooth upgrades for consumers
+
+---
+
+## Questions or Concerns?
+
+If you believe a rule should be changed:
+
+1. Document your reasoning in an issue or discussion
+2. Provide evidence (examples, use cases)
+3. Propose specific changes to the rule
+4. Update CONTRIBUTING.md if rule is changed
+5. Update this file (RULES.md) to reflect new rule
+
+**Do NOT:**
+- Ignore rules because they seem inconvenient
+- Make exceptions without documentation
+- Assume rules don't apply to your changes
+
+---
+
+## Summary Checklist
+
+Before publishing any version:
+
+- [ ] Code matches `.a4drules/skills/component-library/` documentation
+- [ ] CHANGELOG.md updated with all changes
+- [ ] `bash scripts/verify-consistency.sh` passes
+- [ ] `npm run build` succeeds
+- [ ] Postinstall tested in fresh directory
+- [ ] Component names use UI prefix (not shadcn names)
+- [ ] Templates import components correctly
+- [ ] File extensions are .tsx (TypeScript)
+- [ ] Version number in package.json
+- [ ] Git commit includes CHANGELOG changes
+
+**All boxes must be checked before running `npm publish`.**

package/ARCHITECTURE.md

@@ -0,0 +1,112 @@
+# Architecture & Source of Truth
+
+This document defines the authoritative sources for all components, templates, and documentation in this package.
+
+## Core Principle: Documentation is the Contract
+
+**The `.a4drules/skills/component-library/` documentation is the authoritative source of truth.**
+
+- Component names in code MUST match the names in `.a4drules/skills/component-library/ui-primitives.md`
+- Templates MUST import components using the exact names from the documentation
+- If documentation says `UIButton`, the file MUST be `UIButton.tsx` (not `Button.jsx` or `Button.tsx`)
+- If documentation says `UIInput`, the file MUST be `UIInput.tsx` (not `Input.jsx` or `Input.tsx`)
+
+**Never change component names without updating the documentation first.**
+
+## Component Naming Convention
+
+### Library Components (src/components/library/ui/)
+
+Library components use the **UI prefix** to distinguish them from shadcn/outer app components:
+
+```tsx
+// ✅ CORRECT - Library components (for command centers/dashboards)
+UIButton.tsx    // Not Button.tsx or Button.jsx
+UIInput.tsx     // Not Input.tsx or Input.jsx
+UIText.tsx
+UICard.tsx
+UIChip.tsx
+UIContainer.tsx
+UIToggle.tsx
+```
+
+### Shadcn/Outer App Components
+
+Plain names (no prefix) are reserved for the consuming application's outer shell:
+
+```tsx
+// ❌ DO NOT use these names in src/components/library/ui/
+Button.tsx      // Reserved for outer app
+Input.tsx       // Reserved for outer app
+```
+
+### HeroUI Wrapper Components (src/components/library/heroui/)
+
+HeroUI wrappers use the **HeroUI prefix** for advanced components:
+
+```tsx
+// ✅ CORRECT - HeroUI wrappers
+HeroUIButton.tsx
+HeroUIInput.tsx
+HeroUIModal.tsx
+HeroUITabs.tsx
+```
+
+## File Structure Master Reference
+
+```
+sf-web-components/
+├── .a4drules/
+│   ├── skills/
+│   │   └── component-library/     # 📚 SOURCE OF TRUTH for component contracts
+│   │       ├── SKILL.md           # Overview and import patterns
+│   │       ├── ui-primitives.md   # UIButton, UIInput, Avatar, etc.
+│   │       ├── card-components.md # MetricCard, ChartCard, etc.
+│   │       ├── charts.md
+│   │       ├── forms-filters.md
+│   │       ├── chat-data.md
+│   │       ├── hero-ui.md
+│   │       ├── common-mistakes.md # Errors to avoid
+│   │       └── when-to-use.md
+│   └── features/
+│
+├── src/
+│   ├── components/
+│   │   ├── library/               # 📦 IMPLEMENTATION - must match .a4drules docs
+│   │   │   ├── index.jsx          # Barrel export - exports all components
+│   │   │   ├── ui/                # UI primitives (UIButton, UIInput, etc.)
+│   │   │   ├── cards/             # Card components (MetricCard, etc.)
+│   │   │   ├── charts/            # Chart components (D3Chart, GeoMap)
+│   │   │   ├── forms/             # Form components
+│   │   │   ├── filters/           # Filter components
+│   │   │   ├── chat/              # Chat/AI components
+│   │   │   ├── data/              # Data utilities
+│   │   │   ├── layout/            # Layout components
+│   │   │   ├── heroui/            # HeroUI wrappers
+│   │   │   ├── theme/             # Theme provider
+│   │   │   └── skeletons/         # Loading states
+│   │   │
+│   │   └── workspace/
+│   │       └── ComponentRegistry.jsx  # Auto-discovery for command center
+│   │
+│   ├── templates/                 # 📄 TEMPLATES - must import from .a4drules-documented names
+│   │   ├── pages/                 # Page templates
+│   │   │   ├── Home.tsx.template
+│   │   │   ├── Search.tsx.template
+│   │   │   ├── NotFound.tsx.template
+│   │   │   └── BlankDashboard.tsx.template
+│   │   ├── workspace/
+│   │   │   └── CommandCenter.tsx.template
+│   │   └── config/
+│   │       └── routes.tsx.template
+│   │
+│   ├── lib/                       # Utilities (cn, utils)
+│   ├── types/                     # TypeScript types
+│   └── styles/                    # CSS files
+│
+├── scripts/
+│   ├── postinstall.mjs           # 🔧 Copies components & templates to consuming projects
+│   ├── reset-command-center.sh   # Resets CommandCenter to template
+│   └── validate-dashboard.sh     # Validates dashboard compliance
+│
+└── data/                         # Sample data for demos