@schandlergarcia/sf-web-components 1.9.43 → 1.9.44

package/CHANGELOG.md

@@ -0,0 +1,401 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Critical History: Component Naming Crisis (v1.9.29 - v1.9.42)
+
+### The Problem
+
+Between versions 1.9.29 and 1.9.42, a critical inconsistency existed that broke consuming applications:
+
+**Root Cause:** Component files were renamed from `UIButton.tsx`/`UIInput.tsx` to `Button.jsx`/`Input.jsx`, but:
+- Templates still imported `UIButton` and `UIInput`
+- Documentation in `.a4drules/skills/component-library/ui-primitives.md` still referenced `UIButton` and `UIInput`
+- The barrel export still referenced the old paths
+
+**Impact:** New installations failed with "Cannot resolve import" errors because:
+1. NotFound.tsx.template imported `UIButton` from `@/components/library/ui/UIButton`
+2. Home.tsx.template imported `UIButton` and `UIInput` from the same paths
+3. But the package only contained `Button.jsx` and `Input.jsx`
+
+**Why This Happened:** Components were renamed to match shadcn naming convention without understanding that:
+- Shadcn components (`Button`, `Input`) are for the **outer application shell**
+- Library components (`UIButton`, `UIInput`) are for **command centers and dashboards**
+- The `.a4drules/skills/component-library/common-mistakes.md` explicitly documents this distinction
+
+### Timeline of Issues
+
+#### v1.9.25 - v1.9.28 (✅ Golden Versions - Working)
+- **Status:** Fully functional
+- **Components:** `UIButton.tsx`, `UIInput.tsx` (correct names)
+- **Templates:** Import `UIButton` and `UIInput` (matching)
+- **Documentation:** References `UIButton` and `UIInput` (matching)
+- **Evidence:** `/Users/stephan.garcia/reactapp4/` uses v1.9.25 successfully
+
+#### v1.9.29 (❌ Broken - Missing Postinstall)
+- **Issue:** Postinstall script referenced in package.json but not included in published package
+- **Error:** "Cannot find module postinstall.mjs"
+- **Cause:** Missing from package.json `files` array
+
+#### v1.9.30 - v1.9.38 (❌ Broken - Missing Source Files)
+- **Issue:** Removed `src/` directories from package.json `files` array
+- **Error:** Postinstall couldn't find source files to copy
+- **Cause:** Attempted to publish only dist/ but postinstall needs src/ for templates and components
+
+#### v1.9.39 (❌ Broken - Partial Fix)
+- **Issue:** Restored src/ directories but components had wrong names
+- **Components:** `Button.jsx`, `Input.jsx` (wrong - shadcn names)
+- **Templates:** Still importing `UIButton`, `UIInput`
+- **Result:** Import resolution failures
+
+#### v1.9.40 (❌ Broken - Missing Glob Dependency)
+- **Issue:** Postinstall script imports `glob` but it wasn't in dependencies
+- **Error:** "Cannot find package 'glob'"
+- **Added:** `"glob": "^11.0.0"` to dependencies
+
+#### v1.9.41 - v1.9.42 (❌ Broken - Component Naming Mismatch)
+- **Issue:** All other fixes applied but component names still wrong
+- **Components:** `Button.jsx`, `Input.jsx` (shadcn naming)
+- **Templates:** Importing `UIButton`, `UIInput` (library naming)
+- **Documentation:** References `UIButton`, `UIInput` (library naming)
+- **Result:** "Failed to resolve import @/components/library/ui/UIButton"
+
+#### v1.9.43 (✅ Fixed)
+- **Fix:** Restored `UIButton.tsx` and `UIInput.tsx` from golden version
+- **Removed:** Incorrect `Button.jsx` and `Input.jsx` files
+- **Updated:** Barrel export paths to match new file names
+- **Updated:** Internal imports in `ActionList.jsx` and `TableCard.jsx`
+- **Verified:** Templates, components, and documentation all aligned
+- **Result:** Consuming applications install and run successfully
+
+---
+
+## [1.9.44] - 2026-04-01
+
+### Added
+- **ARCHITECTURE.md** - Comprehensive documentation of source of truth hierarchy
+  - Documents that `.a4drules/skills/component-library/` is authoritative
+  - Explains component naming convention (UI prefix for library, plain names for outer app)
+  - File structure master reference with clear responsibilities
+  
+- **CONTRIBUTING.md** - Detailed contribution guidelines
+  - Change process with correct order (docs → code → templates → exports)
+  - Component naming rules with examples
+  - Template import rules
+  - Pre-release checklist (9 required steps)
+  - Common mistakes and how to avoid them
+  - Recovery procedures for bad releases
+  
+- **CHANGELOG.md** - This file with complete version history
+  - Detailed timeline of v1.9.29-v1.9.42 naming crisis
+  - Root cause analysis of why templates broke
+  - Version-by-version breakdown of issues
+  - Documentation standards for future changelog entries
+  
+- **QUICK-REFERENCE.md** - One-page quick reference card
+  - Pre-publish checklist
+  - Component naming table
+  - Source of truth hierarchy
+  - Common errors and fixes
+  - Emergency recovery procedures
+  
+- **.a4drules/RULES.md** - Mandatory project rules
+  - 10 enforced rules for all contributors and AI assistants
+  - Rule 1: Documentation is source of truth
+  - Rule 2: CHANGELOG.md is mandatory
+  - Rule 3-10: Component naming, templates, testing, versioning
+  - Pre-commit verification hooks
+  
+- **scripts/verify-consistency.sh** - Automated consistency verification
+  - Checks component files exist (UIButton.tsx, UIInput.tsx)
+  - Verifies barrel export paths
+  - Validates template imports
+  - Checks internal library imports
+  - Verifies documentation references
+  - Validates package.json files array
+  - Exit code 0 if all checks pass, 1 if any fail
+  
+- **scripts/pre-publish-check.sh** - Pre-publish verification script
+  - Runs all consistency checks
+  - Verifies CHANGELOG has entry for current version
+  - Checks component naming conventions
+  - Runs build to verify no errors
+  - Validates documentation files exist
+  - Checks package.json files array
+  - Blocks publish if any check fails
+
+### Changed
+- **package.json scripts** - Added verification scripts
+  - Added `verify`: Run consistency checks
+  - Added `prepublish:check`: Run all pre-publish checks
+  - Updated `prepublishOnly`: Now runs verification before build
+  - Publishing now automatically blocked if verification fails
+  
+- **package.json files array** - Added documentation files
+  - Added CHANGELOG.md
+  - Added CONTRIBUTING.md
+  - Added ARCHITECTURE.md
+  - Added QUICK-REFERENCE.md
+  - These files now ship with the package
+  
+- **README.md** - Updated with contribution and publishing sections
+  - Added Contributing section with links to all docs
+  - Updated Publishing section to document automated verification
+  - Changed import examples to use UIButton (not Button)
+  - Added verification command examples
+
+### Documentation
+- Created comprehensive documentation system to prevent future naming issues
+- All rules, processes, and guidelines now documented in multiple formats:
+  - Detailed guides (CONTRIBUTING.md, ARCHITECTURE.md)
+  - Quick reference (QUICK-REFERENCE.md)
+  - Mandatory rules (.a4drules/RULES.md)
+  - Version history (CHANGELOG.md)
+- Added guide for consuming projects (internal-app-standard-config/.a4drules/sf-web-components-guide.md)
+
+### Infrastructure
+- Automated pre-publish verification prevents broken releases
+- Scripts enforce consistency between docs, code, and templates
+- Cannot publish without CHANGELOG entry
+- Cannot publish with naming mismatches
+- Cannot publish if build fails
+
+### Purpose
+This release adds comprehensive documentation and automation to ensure the component naming crisis of v1.9.29-v1.9.42 **never happens again**:
+
+**The Problem We're Preventing:**
+- Components renamed without updating templates → Import failures
+- Changes made without updating CHANGELOG → Lost history
+- Code changed without checking documentation → Contract violations
+- Published without testing → Broken consuming applications
+
+**How We're Preventing It:**
+- Automated verification scripts run on every publish
+- Comprehensive documentation at multiple levels
+- Clear source of truth hierarchy
+- Mandatory CHANGELOG updates
+- Pre-commit hooks (optional but recommended)
+
+### Breaking Changes
+None - This is a documentation and tooling release
+
+### Migration
+No migration needed. This version adds documentation and verification tools but does not change any component APIs.
+
+If you're maintaining or contributing to sf-web-components:
+1. Read CONTRIBUTING.md before making changes
+2. Run `npm run verify` before committing
+3. Update CHANGELOG.md with every change
+4. The `prepublishOnly` hook will enforce these rules
+
+---
+
+## [1.9.43] - 2026-04-01
+
+### Fixed
+- **CRITICAL:** Restored UIButton.tsx and UIInput.tsx with correct naming convention
+  - Component files now match template imports and documentation
+  - Fixes "Cannot resolve import @/components/library/ui/UIButton" error
+  - Copied from golden version (v1.9.25) at `/Users/stephan.garcia/reactapp4/`
+- Removed incorrect Button.jsx and Input.jsx files (shadcn naming reserved for outer app)
+- Updated barrel export in src/components/library/index.jsx:
+  - Changed `from "./ui/Button"` to `from "./ui/UIButton"`
+  - Changed `from "./ui/Input"` to `from "./ui/UIInput"`
+- Fixed internal imports in:
+  - src/components/library/cards/ActionList.jsx
+  - src/components/library/cards/TableCard.jsx
+
+### Added
+- ARCHITECTURE.md - Documents source of truth and naming conventions
+- CONTRIBUTING.md - Comprehensive guide to prevent future naming issues
+- scripts/verify-consistency.sh - Automated verification of component/template/doc alignment
+- This CHANGELOG.md - Detailed history and requirements for all future changes
+
+### Documentation
+- Confirmed .a4drules/skills/component-library/ui-primitives.md is authoritative source
+- Confirmed .a4drules/skills/component-library/common-mistakes.md prohibits shadcn names in library
+
+### Breaking Changes
+None - This version restores functionality that was broken in v1.9.29-v1.9.42
+
+### Migration from v1.9.42
+If you're using v1.9.42 (broken version):
+```bash
+# Update to fixed version
+npm install @schandlergarcia/sf-web-components@1.9.43
+
+# Re-run postinstall to copy correct components
+rm -rf src/components/library
+node node_modules/@schandlergarcia/sf-web-components/scripts/postinstall.mjs
+```
+
+---
+
+## [1.9.42] - 2026-03-31
+
+### Known Issues
+- ❌ Button.jsx and Input.jsx exist instead of UIButton.tsx and UIInput.tsx
+- ❌ Templates import UIButton/UIInput but files don't exist
+- ❌ Consuming applications fail to build
+
+### Fixed
+- Restored comprehensive postinstall.mjs script
+- Added "data" directory to package.json files array
+- Re-added glob dependency
+
+---
+
+## [1.9.40] - 2026-03-31
+
+### Added
+- glob dependency to package.json dependencies
+
+### Known Issues
+- ❌ Component naming still incorrect (Button.jsx instead of UIButton.tsx)
+
+---
+
+## [1.9.29 - 1.9.39] - 2026-03-31
+
+### Known Issues
+- Various combinations of missing files, missing dependencies, and incorrect naming
+- All versions in this range are broken for new installations
+
+---
+
+## [1.9.28] - 2026-03-31
+
+### Status
+✅ Last known working version before naming crisis
+
+### Components
+- UIButton.tsx ✅
+- UIInput.tsx ✅
+- All templates import correctly ✅
+- Documentation matches implementation ✅
+
+---
+
+## [1.9.25] - 2026-03-30
+
+### Status
+✅ Golden reference version
+
+### Components
+- UIButton.tsx ✅
+- UIInput.tsx ✅
+- Complete component library
+- Working postinstall script
+- All templates functional
+
+### Evidence
+Used successfully in production project at `/Users/stephan.garcia/reactapp4/`
+
+---
+
+## Versioning Policy
+
+### When to Bump Versions
+
+#### Patch (1.9.x)
+- Bug fixes
+- Documentation updates
+- Internal refactoring that doesn't affect API
+
+#### Minor (1.x.0)
+- New components added
+- New features added
+- Backward-compatible API changes
+
+#### Major (x.0.0)
+- Breaking changes to component APIs
+- Component renames that affect imports
+- Removal of deprecated components
+
+### Pre-Release Checklist
+
+**REQUIRED before every publish:**
+
+1. [ ] Run `bash scripts/verify-consistency.sh` (must pass)
+2. [ ] Run `npm run build` (must succeed)
+3. [ ] Update CHANGELOG.md with changes
+4. [ ] Test postinstall in a fresh directory
+5. [ ] Verify component names match .a4drules documentation
+6. [ ] Verify templates import components correctly
+7. [ ] Check package.json files array includes all necessary directories
+
+**Never skip these steps.**
+
+---
+
+## Documentation Standards
+
+### Changelog Requirements
+
+Every version entry MUST include:
+
+1. **Version number and date**
+   ```markdown
+   ## [1.9.43] - 2026-04-01
+   ```
+
+2. **Category sections** (as applicable):
+   - Added - New features
+   - Changed - Changes to existing functionality
+   - Deprecated - Soon-to-be removed features
+   - Removed - Removed features
+   - Fixed - Bug fixes
+   - Security - Security fixes
+
+3. **Component changes** (if any):
+   - List every component file added, removed, or renamed
+   - Explain why the change was made
+   - Document impact on templates and consuming projects
+
+4. **Breaking changes** (if any):
+   - Clearly marked with ⚠️ or "BREAKING"
+   - Migration instructions
+   - Affected versions
+
+5. **Known issues** (if any):
+   - Marked with ❌
+   - Description of the issue
+   - Workaround if available
+
+### Example Good Changelog Entry
+
+```markdown
+## [1.9.43] - 2026-04-01
+
+### Fixed
+- **CRITICAL:** Restored UIButton.tsx and UIInput.tsx
+  - Fixes "Cannot resolve import" errors in templates
+  - Matches documented API in .a4drules/skills/component-library/
+  - Removed incorrect Button.jsx and Input.jsx files
+
+### Added
+- CONTRIBUTING.md - Contribution guidelines
+- scripts/verify-consistency.sh - Pre-publish validation
+
+### Migration
+Update package version and re-run postinstall:
+\`\`\`bash
+npm install @schandlergarcia/sf-web-components@1.9.43
+node node_modules/@schandlergarcia/sf-web-components/scripts/postinstall.mjs
+\`\`\`
+```
+
+---
+
+## Questions?
+
+If you're unsure about:
+- **Naming:** Check `.a4drules/skills/component-library/ui-primitives.md`
+- **Changes:** Review this CHANGELOG for patterns
+- **Testing:** Run `scripts/verify-consistency.sh`
+- **Publishing:** Follow CONTRIBUTING.md checklist
+
+**When in doubt, check against golden version 1.9.25-1.9.28.**

package/CONTRIBUTING.md

@@ -0,0 +1,247 @@
+# Contributing to sf-web-components
+
+## Critical Rules
+
+### 1. Documentation is the Source of Truth
+
+**Before making ANY changes to component names, check `.a4drules/skills/component-library/` first.**
+
+The documentation in `.a4drules/skills/component-library/` defines the contract. Code must match documentation, not the other way around.
+
+#### Change Process (ALWAYS follow this order):
+
+1. **Update `.a4drules/skills/component-library/` documentation FIRST**
+2. Update the component implementation in `src/components/library/`
+3. Update templates in `src/templates/` to use the new names
+4. Update barrel export in `src/components/library/index.jsx`
+5. Update any internal imports in `src/components/library/`
+6. Run `npm run build` to verify
+7. Test the postinstall script
+8. Publish new version
+
+**Never skip step 1.** If you change code without updating docs first, you break the contract.
+
+### 2. Component Naming Rules
+
+#### Library Components Must Use UI Prefix
+
+```tsx
+// ✅ CORRECT
+src/components/library/ui/UIButton.tsx
+src/components/library/ui/UIInput.tsx
+
+// ❌ WRONG - These names are reserved for outer app shadcn components
+src/components/library/ui/Button.tsx
+src/components/library/ui/Input.tsx
+```
+
+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`)"
+
+#### File Extensions Matter
+
+- Use `.tsx` for TypeScript files with JSX
+- Use `.jsx` only for pure JavaScript files with JSX
+- Prefer TypeScript (`.tsx`) for all new components
+
+### 3. Template Import Rules
+
+Templates in `src/templates/` MUST import components using the exact names from `.a4drules/skills/component-library/`:
+
+```tsx
+// ✅ CORRECT - Matches ui-primitives.md documentation
+import UIButton from '@/components/library/ui/UIButton';
+import UIInput from '@/components/library/ui/UIInput';
+
+// ❌ WRONG - Does not match documentation
+import Button from '@/components/library/ui/Button';
+import Input from '@/components/library/ui/Input';
+```
+
+### 4. Barrel Export Consistency
+
+The barrel export at `src/components/library/index.jsx` MUST match both:
+1. The actual file names in `src/components/library/ui/`
+2. The component names in `.a4drules/skills/component-library/ui-primitives.md`
+
+```jsx
+// ✅ CORRECT
+export { default as UIButton } from "./ui/UIButton";
+export { default as UIInput } from "./ui/UIInput";
+
+// ❌ WRONG
+export { default as UIButton } from "./ui/Button";  // File doesn't exist
+export { default as UIInput } from "./ui/Input";    // File doesn't exist
+```
+
+## Pre-Release Checklist
+
+Before publishing any version, verify:
+
+### 1. Documentation Check
+- [ ] All component names in code match `.a4drules/skills/component-library/` docs
+- [ ] No new components added without documentation
+- [ ] `common-mistakes.md` updated if new patterns emerge
+
+### 2. Component Check
+```bash
+# UIButton and UIInput MUST exist as .tsx files
+ls src/components/library/ui/UIButton.tsx
+ls src/components/library/ui/UIInput.tsx
+
+# Button.jsx and Input.jsx should NOT exist in library/ui/
+# (They can exist in heroui/ but not in ui/)
+! ls src/components/library/ui/Button.jsx 2>/dev/null
+! ls src/components/library/ui/Input.jsx 2>/dev/null
+```
+
+### 3. Template Check
+```bash
+# All templates must import UIButton (not Button)
+grep -r "from '@/components/library/ui/UIButton'" src/templates/
+
+# No template should import Button from ui/
+! grep -r "from '@/components/library/ui/Button'" src/templates/
+```
+
+### 4. Build Check
+```bash
+npm run build
+# Must succeed with no errors
+```
+
+### 5. Postinstall Check
+```bash
+# Create test directory
+mkdir -p /tmp/test-sf-components && cd /tmp/test-sf-components
+
+# Initialize minimal package.json
+cat > package.json << 'EOF'
+{
+  "name": "test-project",
+  "version": "1.0.0",
+  "type": "module"
+}
+EOF
+
+# Create minimal structure
+mkdir -p src/pages src/components/library/ui
+
+# Install package (will run postinstall)
+npm install @schandlergarcia/sf-web-components@latest
+
+# Verify UIButton was copied
+ls src/components/library/ui/UIButton.tsx
+ls src/components/library/ui/UIInput.tsx
+
+# Verify templates were installed
+ls src/pages/NotFound.tsx
+
+# Verify NotFound imports UIButton
+grep "UIButton" src/pages/NotFound.tsx
+```
+
+### 6. Version and Publish
+```bash
+# Bump version
+npm version patch  # or minor, or major
+
+# Publish
+npm publish
+```
+
+## Common Mistakes to Avoid
+
+### Mistake #1: Renaming Components Without Updating Docs
+
+```bash
+# ❌ WRONG - Changed code but not docs
+mv src/components/library/ui/UIButton.tsx src/components/library/ui/Button.tsx
+# Now templates fail because they import UIButton
+
+# ✅ CORRECT - Update docs first
+# 1. Edit .a4drules/skills/component-library/ui-primitives.md
+#    Change "UIButton" to "Button"
+# 2. Update templates to import Button
+# 3. Then rename the file
+```
+
+### Mistake #2: Using shadcn Names in Library
+
+```bash
+# ❌ WRONG - Using shadcn naming convention
+src/components/library/ui/Button.jsx
+src/components/library/ui/Input.jsx
+
+# ✅ CORRECT - Using library naming convention
+src/components/library/ui/UIButton.tsx
+src/components/library/ui/UIInput.tsx
+```
+
+### Mistake #3: Inconsistent File Extensions
+
+```bash
+# ❌ WRONG - Mixing .jsx and .tsx inconsistently
+src/components/library/ui/UIButton.jsx    # JavaScript
+src/components/library/ui/UIInput.tsx     # TypeScript
+
+# ✅ CORRECT - Consistent TypeScript
+src/components/library/ui/UIButton.tsx
+src/components/library/ui/UIInput.tsx
+```
+
+### Mistake #4: Forgetting to Update Barrel Export
+
+```jsx
+// ❌ WRONG - File renamed but export not updated
+// File: src/components/library/ui/UIButton.tsx
+// But index.jsx still has:
+export { default as UIButton } from "./ui/Button";  // ❌ Wrong path
+
+// ✅ CORRECT
+export { default as UIButton } from "./ui/UIButton";  // ✅ Matches file
+```
+
+### Mistake #5: Not Testing Postinstall
+
+```bash
+# ❌ WRONG - Publishing without testing postinstall
+npm publish
+
+# ✅ CORRECT - Test postinstall first
+npm pack
+cd /tmp/test-package
+npm install /path/to/sf-web-components-1.9.43.tgz
+# Verify files copied correctly
+ls src/components/library/ui/UIButton.tsx
+```
+
+## Recovery from Bad Release
+
+If a broken version was published:
+
+1. **Do NOT use `npm unpublish`** (breaks downstream projects)
+2. Fix the issue following the correct process above
+3. Publish a new patch version immediately
+4. Document the issue in CHANGELOG.md
+
+## Golden Reference Version
+
+**Version 1.9.25-1.9.28** is the golden reference that works correctly.
+
+If you need to verify correct structure:
+```bash
+npm view @schandlergarcia/sf-web-components@1.9.28 --json
+```
+
+Working consuming project example: `/Users/stephan.garcia/reactapp4/` uses v1.9.25 successfully.
+
+## Questions?
+
+If you're unsure about naming or structure:
+
+1. Check `.a4drules/skills/component-library/` documentation FIRST
+2. Check golden version 1.9.25-1.9.28
+3. Check working example in `/Users/stephan.garcia/reactapp4/`
+4. Ask before making changes