@schandlergarcia/sf-web-components 1.9.43 → 1.9.45

package/QUICK-REFERENCE.md

@@ -0,0 +1,212 @@
+# Quick Reference Card
+
+## Before Publishing - Checklist
+
+```bash
+# 1. Update CHANGELOG.md
+vim CHANGELOG.md
+
+# 2. Run verification
+npm run verify
+
+# 3. Run pre-publish checks
+npm run prepublish:check
+
+# 4. Bump version
+npm version patch
+
+# 5. Publish (verification runs automatically)
+npm publish
+```
+
+## Component Naming
+
+| ✅ CORRECT | ❌ WRONG | Reason |
+|-----------|---------|--------|
+| `UIButton.tsx` | `Button.tsx` | Library uses UI prefix |
+| `UIInput.tsx` | `Input.tsx` | Library uses UI prefix |
+| `UIButton.tsx` | `Button.jsx` | Use TypeScript .tsx |
+| Import from `UIButton` | Import from `Button` | Must match file name |
+
+## Source of Truth Hierarchy
+
+```
+1. .a4drules/skills/component-library/     ← DOCUMENTATION (source of truth)
+2. src/components/library/                 ← CODE (must match docs)
+3. src/templates/                          ← TEMPLATES (must match docs)
+4. CHANGELOG.md                            ← HISTORY (must document all changes)
+```
+
+## File Structure
+
+```
+src/components/library/ui/
+  ✅ UIButton.tsx          (Library component)
+  ✅ UIInput.tsx           (Library component)
+  ❌ Button.tsx            (Reserved for outer app)
+  ❌ Input.tsx             (Reserved for outer app)
+
+src/templates/pages/
+  ✅ Home.tsx.template     (Imports UIButton, UIInput)
+  ✅ NotFound.tsx.template (Imports UIButton)
+
+.a4drules/skills/component-library/
+  📚 ui-primitives.md      (Documents UIButton, UIInput)
+  📚 common-mistakes.md    (Lists UIButton vs Button rule)
+```
+
+## Import Patterns
+
+### ✅ Correct
+
+```tsx
+// Template imports
+import UIButton from '@/components/library/ui/UIButton';
+import UIInput from '@/components/library/ui/UIInput';
+
+// Barrel export
+export { default as UIButton } from "./ui/UIButton";
+export { default as UIInput } from "./ui/UIInput";
+
+// Consuming app imports
+import { UIButton, UIInput, MetricCard } from '@/components/library';
+```
+
+### ❌ Wrong
+
+```tsx
+// ❌ Don't import from non-existent files
+import Button from '@/components/library/ui/Button';
+import Input from '@/components/library/ui/Input';
+
+// ❌ Don't use wrong paths in barrel export
+export { default as UIButton } from "./ui/Button";  // File doesn't exist
+
+// ❌ Don't use shadcn names in library
+import { Button } from '@/components/library';
+```
+
+## Verification Commands
+
+| Command | Purpose | When to Run |
+|---------|---------|-------------|
+| `npm run verify` | Check consistency | Before committing |
+| `npm run prepublish:check` | Full pre-publish checks | Before publishing |
+| `npm run build` | Build dist/ | After changes |
+| `bash scripts/verify-consistency.sh` | Detailed consistency check | Manual verification |
+
+## Common Errors and Fixes
+
+### Error: "Cannot resolve import '@/components/library/ui/UIButton'"
+
+**Cause:** Component file is named `Button.tsx` but imports expect `UIButton.tsx`
+
+**Fix:**
+```bash
+# Rename to correct name
+mv src/components/library/ui/Button.tsx src/components/library/ui/UIButton.tsx
+
+# Update barrel export
+# Change: from "./ui/Button"
+# To:     from "./ui/UIButton"
+```
+
+### Error: "CHANGELOG missing entry for version X.X.X"
+
+**Cause:** Version was bumped but CHANGELOG.md not updated
+
+**Fix:**
+```bash
+vim CHANGELOG.md
+# Add:
+## [X.X.X] - 2026-04-01
+### Fixed
+- Description of changes
+```
+
+### Error: "Consistency check failed"
+
+**Cause:** Mismatch between docs, code, or templates
+
+**Fix:**
+```bash
+# Run verification to see details
+npm run verify
+
+# Fix reported issues
+# - Check .a4drules/skills/component-library/ui-primitives.md for correct names
+# - Update code to match docs
+# - Update templates to match docs
+```
+
+## Golden Reference
+
+**Version 1.9.25-1.9.28** are the golden reference versions.
+
+```bash
+# View golden version structure
+npm view @schandlergarcia/sf-web-components@1.9.28
+
+# Check working example
+ls /Users/stephan.garcia/reactapp4/src/components/library/ui/
+```
+
+## Emergency Recovery
+
+If you published a broken version:
+
+```bash
+# 1. Don't unpublish (breaks downstream)
+# 2. Fix the issue immediately
+# 3. Publish patch version
+
+# Example:
+# v1.9.42 published with Button.jsx (wrong)
+
+# Fix:
+cd sf-web-components
+git checkout v1.9.28 -- src/components/library/ui/UIButton.tsx
+git checkout v1.9.28 -- src/components/library/ui/UIInput.tsx
+rm src/components/library/ui/Button.jsx
+rm src/components/library/ui/Input.jsx
+
+# Update exports
+vim src/components/library/index.jsx
+# Change: from "./ui/Button" → from "./ui/UIButton"
+# Change: from "./ui/Input" → from "./ui/UIInput"
+
+# Update changelog
+vim CHANGELOG.md
+# Document the fix
+
+# Publish fix
+npm version patch
+npm publish
+```
+
+## Key Documents
+
+| Document | Purpose | Read When |
+|----------|---------|-----------|
+| [ARCHITECTURE.md](./ARCHITECTURE.md) | System structure | Starting new work |
+| [CONTRIBUTING.md](./CONTRIBUTING.md) | Contribution guide | Before first commit |
+| [CHANGELOG.md](./CHANGELOG.md) | Version history | Before each release |
+| [.a4drules/RULES.md](./.a4drules/RULES.md) | Mandatory rules | Always follow |
+| [.a4drules/skills/component-library/](./a4drules/skills/component-library/) | Component API docs | When using components |
+
+## Questions?
+
+1. ❓ "What should I name this component?" → Check `.a4drules/skills/component-library/ui-primitives.md`
+2. ❓ "Can I rename this component?" → NO, unless you update docs first (see CONTRIBUTING.md)
+3. ❓ "Why UIButton not Button?" → See `.a4drules/skills/component-library/common-mistakes.md`
+4. ❓ "What version works?" → 1.9.25-1.9.28 and 1.9.43+
+5. ❓ "Can I skip verification?" → NO, it will fail at publish time anyway
+
+## Remember
+
+- **Documentation = Contract** - Code must match docs
+- **CHANGELOG = Required** - Update with every change
+- **UI Prefix = Library** - UIButton, UIInput (not Button, Input)
+- **Templates = Must Match** - Imports must match file names
+- **Verify = Always** - Run before committing and publishing
+- **Golden = Reference** - v1.9.25-1.9.28 when in doubt

package/README.md

@@ -20,18 +20,25 @@ This package requires:
 ### Import Components
 
 ```tsx
-import { Button, Card } from '@schandlergarcia/sf-web-components';
-import { cn } from '@schandlergarcia/sf-web-components/lib';
+// Library components (for command centers/dashboards)
+import { UIButton, MetricCard } from '@/components/library';
+import { cn } from '@/lib/utils';
 
-function App() {
+function Dashboard() {
   return (
-    <Card className={cn('p-4')}>
-      <Button>Click me</Button>
-    </Card>
+    <MetricCard
+      title="Total Sales"
+      value="$1.2M"
+      trend={{ value: 12, direction: 'up' }}
+      footer={<UIButton variant="primary">View Details</UIButton>}
+    />
   );
 }
 ```
 
+**Note:** After installation, components are copied to `src/components/library/` for Tailwind scanning.
+Import from `@/components/library` (not from the package directly).
+
 ### Import Styles
 
 Add to your main CSS file:
@@ -105,6 +112,32 @@ npm run build
 npm run build:types
 ```
 
+## Contributing
+
+**⚠️ IMPORTANT: Read [CONTRIBUTING.md](./CONTRIBUTING.md) before making changes.**
+
+### Key Rules
+- Component names MUST match `.a4drules/skills/component-library/` documentation
+- Library components use **UI prefix** (UIButton, UIInput) - NOT shadcn names
+- Update CHANGELOG.md with EVERY change before publishing
+- Run verification scripts before committing
+
+### Quick Checks
+
+```bash
+# Verify consistency between code, docs, and templates
+npm run verify
+
+# Pre-publish verification (runs automatically before publish)
+npm run prepublish:check
+```
+
+### Documentation Structure
+- **[ARCHITECTURE.md](./ARCHITECTURE.md)** - Source of truth hierarchy
+- **[CONTRIBUTING.md](./CONTRIBUTING.md)** - Contribution guidelines and checklists
+- **[CHANGELOG.md](./CHANGELOG.md)** - Detailed version history
+- **[.a4drules/RULES.md](./.a4drules/RULES.md)** - Mandatory project rules
+
 ## Publishing
 
 This package publishes to the **public npm registry** at https://registry.npmjs.org.
@@ -113,21 +146,50 @@ This package publishes to the **public npm registry** at https://registry.npmjs.
 - Be logged in to npm: `npm login`
 - Have publish permissions for the `@schandlergarcia` scope
 
-### Publish a New Version
+### Publish Process
+
+**The `prepublishOnly` script automatically runs verification checks.**
 
 ```bash
-# Bump version (patch, minor, or major)
-npm version patch  # 1.9.29 → 1.9.30
-npm version minor  # 1.9.29 → 1.10.0
-npm version major  # 1.9.29 → 2.0.0
+# 1. Update CHANGELOG.md with your changes
+#    Add entry under ## [X.X.X] - YYYY-MM-DD
 
-# Or manually edit package.json version field
+# 2. Bump version
+npm version patch  # 1.9.43 → 1.9.44
+npm version minor  # 1.9.43 → 1.10.0
+npm version major  # 1.9.43 → 2.0.0
 
-# Build and publish
-npm run build
+# 3. Publish (verification runs automatically)
 npm publish
 ```
 
+**The prepublishOnly hook will:**
+1. Run consistency verification (`npm run verify`)
+2. Check CHANGELOG has entry for current version
+3. Verify UIButton.tsx and UIInput.tsx exist
+4. Build the package
+5. Block publish if any checks fail
+
+### Manual Verification (Optional)
+
+```bash
+# Run all pre-publish checks manually
+npm run prepublish:check
+
+# Run only consistency checks
+npm run verify
+```
+
+### If Publish Fails
+
+If verification fails:
+1. Read the error output carefully
+2. Fix the reported issues
+3. See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidance
+4. See [.a4drules/RULES.md](./.a4drules/RULES.md) for rules
+5. Run `npm run verify` to check fixes
+6. Try publishing again
+
 The package is published as **public** and can be installed by anyone:
 ```bash
 npm install @schandlergarcia/sf-web-components

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schandlergarcia/sf-web-components",
-  "version": "1.9.43",
+  "version": "1.9.45",
   "description": "Reusable Salesforce web components library with Tailwind CSS v4 and shadcn/ui",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,12 +34,18 @@
     "src/types",
     "README.md",
     "INSTALL.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "ARCHITECTURE.md",
+    "QUICK-REFERENCE.md",
     ".a4drules"
   ],
   "scripts": {
     "build": "vite build && cp -r src/styles dist/",
     "build:types": "tsc --emitDeclarationOnly",
-    "prepublishOnly": "npm run build",
+    "verify": "bash scripts/verify-consistency.sh",
+    "prepublish:check": "bash scripts/pre-publish-check.sh",
+    "prepublishOnly": "npm run prepublish:check && npm run build",
     "postinstall": "node scripts/postinstall.mjs",
     "reset:command-center": "bash scripts/reset-command-center.sh",
     "validate:dashboard": "bash scripts/validate-dashboard.sh",

package/scripts/pre-publish-check.sh

@@ -0,0 +1,180 @@
+#!/bin/bash
+
+# Pre-publish verification script
+# Enforces all rules from .a4drules/RULES.md before allowing publish
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🔒 Pre-Publish Verification"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+ERRORS=0
+
+# Rule 1: Consistency Check
+echo "📋 Rule 1: Verifying consistency between code, docs, and templates..."
+if bash "$ROOT/scripts/verify-consistency.sh"; then
+  echo -e "${GREEN}✓ Consistency check passed${NC}"
+else
+  echo -e "${RED}✗ Consistency check failed${NC}"
+  ERRORS=$((ERRORS + 1))
+fi
+echo ""
+
+# Rule 2: CHANGELOG Check
+echo "📝 Rule 2: Verifying CHANGELOG.md is up to date..."
+
+# Get current version from package.json
+VERSION=$(node -p "require('$ROOT/package.json').version")
+echo "  Current version: $VERSION"
+
+# Check if CHANGELOG has entry for current version
+if grep -q "## \[$VERSION\]" "$ROOT/CHANGELOG.md"; then
+  echo -e "  ${GREEN}✓ CHANGELOG has entry for version $VERSION${NC}"
+else
+  echo -e "  ${RED}✗ CHANGELOG missing entry for version $VERSION${NC}"
+  echo "  Add a section to CHANGELOG.md:"
+  echo "  ## [$VERSION] - $(date +%Y-%m-%d)"
+  ERRORS=$((ERRORS + 1))
+fi
+
+# Check if any src/ files changed since last commit
+if git diff --name-only HEAD src/ 2>/dev/null | grep -q .; then
+  echo -e "  ${YELLOW}⚠ src/ files changed, ensure CHANGELOG is updated${NC}"
+fi
+
+echo ""
+
+# Rule 3: Component Naming
+echo "🏷️  Rule 3: Verifying component naming conventions..."
+if [ -f "$ROOT/src/components/library/ui/UIButton.tsx" ]; then
+  echo -e "  ${GREEN}✓ UIButton.tsx exists (correct)${NC}"
+else
+  echo -e "  ${RED}✗ UIButton.tsx missing${NC}"
+  ERRORS=$((ERRORS + 1))
+fi
+
+if [ -f "$ROOT/src/components/library/ui/UIInput.tsx" ]; then
+  echo -e "  ${GREEN}✓ UIInput.tsx exists (correct)${NC}"
+else
+  echo -e "  ${RED}✗ UIInput.tsx missing${NC}"
+  ERRORS=$((ERRORS + 1))
+fi
+
+if [ -f "$ROOT/src/components/library/ui/Button.jsx" ] || [ -f "$ROOT/src/components/library/ui/Button.tsx" ]; then
+  echo -e "  ${RED}✗ Button.jsx/tsx exists (should be UIButton.tsx)${NC}"
+  ERRORS=$((ERRORS + 1))
+fi
+
+if [ -f "$ROOT/src/components/library/ui/Input.jsx" ] || [ -f "$ROOT/src/components/library/ui/Input.tsx" ]; then
+  echo -e "  ${RED}✗ Input.jsx/tsx exists (should be UIInput.tsx)${NC}"
+  ERRORS=$((ERRORS + 1))
+fi
+
+echo ""
+
+# Rule 4: Build Check
+echo "🔨 Rule 4: Verifying build succeeds..."
+if npm run build --silent; then
+  echo -e "${GREEN}✓ Build succeeded${NC}"
+else
+  echo -e "${RED}✗ Build failed${NC}"
+  ERRORS=$((ERRORS + 1))
+fi
+echo ""
+
+# Rule 5: Documentation Check
+echo "📚 Rule 5: Verifying documentation files exist..."
+if [ -f "$ROOT/.a4drules/skills/component-library/ui-primitives.md" ]; then
+  echo -e "  ${GREEN}✓ ui-primitives.md exists${NC}"
+else
+  echo -e "  ${RED}✗ ui-primitives.md missing${NC}"
+  ERRORS=$((ERRORS + 1))
+fi
+
+if [ -f "$ROOT/CHANGELOG.md" ]; then
+  echo -e "  ${GREEN}✓ CHANGELOG.md exists${NC}"
+else
+  echo -e "  ${RED}✗ CHANGELOG.md missing${NC}"
+  ERRORS=$((ERRORS + 1))
+fi
+
+if [ -f "$ROOT/CONTRIBUTING.md" ]; then
+  echo -e "  ${GREEN}✓ CONTRIBUTING.md exists${NC}"
+else
+  echo -e "  ${RED}✗ CONTRIBUTING.md missing${NC}"
+  ERRORS=$((ERRORS + 1))
+fi
+
+if [ -f "$ROOT/ARCHITECTURE.md" ]; then
+  echo -e "  ${GREEN}✓ ARCHITECTURE.md exists${NC}"
+else
+  echo -e "  ${RED}✗ ARCHITECTURE.md missing${NC}"
+  ERRORS=$((ERRORS + 1))
+fi
+
+if [ -f "$ROOT/.a4drules/RULES.md" ]; then
+  echo -e "  ${GREEN}✓ RULES.md exists${NC}"
+else
+  echo -e "  ${RED}✗ RULES.md missing${NC}"
+  ERRORS=$((ERRORS + 1))
+fi
+
+echo ""
+
+# Rule 6: Package.json files array check
+echo "📦 Rule 6: Verifying package.json files array..."
+REQUIRED_DIRS=("src/templates" "src/components" "src/lib" "src/types" ".a4drules" "scripts")
+
+for dir in "${REQUIRED_DIRS[@]}"; do
+  if grep -q "\"$dir\"" "$ROOT/package.json"; then
+    echo -e "  ${GREEN}✓ $dir included${NC}"
+  else
+    echo -e "  ${RED}✗ $dir missing from files array${NC}"
+    ERRORS=$((ERRORS + 1))
+  fi
+done
+
+echo ""
+
+# Rule 7: Git status check
+echo "🔍 Rule 7: Checking git status..."
+if git diff-index --quiet HEAD -- 2>/dev/null; then
+  echo -e "${GREEN}✓ No uncommitted changes${NC}"
+else
+  echo -e "${YELLOW}⚠ You have uncommitted changes${NC}"
+  echo "  Consider committing before publishing"
+fi
+echo ""
+
+# Summary
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+if [ $ERRORS -eq 0 ]; then
+  echo -e "${GREEN}✅ All pre-publish checks passed!${NC}"
+  echo ""
+  echo "Safe to publish version $VERSION"
+  echo ""
+  echo "To publish, run:"
+  echo "  npm publish"
+  echo ""
+  exit 0
+else
+  echo -e "${RED}❌ Found $ERRORS error(s)${NC}"
+  echo ""
+  echo "Cannot publish until all errors are fixed."
+  echo ""
+  echo "See .a4drules/RULES.md for requirements"
+  echo "See CONTRIBUTING.md for guidance"
+  echo ""
+  exit 1
+fi

package/scripts/reset-command-center.sh

@@ -39,11 +39,14 @@ echo ""
 echo "→ Removing custom dashboards…"
 
 removed=0
-for f in src/components/pages/*Dashboard*.jsx src/components/pages/*Dashboard*.tsx; do
+for f in src/pages/*Dashboard*.jsx src/pages/*Dashboard*.tsx; do
   if [ -f "$f" ]; then
-    rm "$f"
-    echo "  ✓ Removed $(basename "$f")"
-    removed=$((removed + 1))
+    # Don't remove BlankDashboard.tsx (it's the template)
+    if [[ "$(basename "$f")" != "BlankDashboard.tsx" ]]; then
+      rm "$f"
+      echo "  ✓ Removed $(basename "$f")"
+      removed=$((removed + 1))
+    fi
   fi
 done
 
@@ -54,11 +57,13 @@ echo ""
 
 # ── 2. Write the blank starter dashboard ────────────────────────────────────
 
-BLANK="src/components/pages/BlankDashboard.jsx"
+# Ensure src/pages directory exists
+mkdir -p src/pages
+
+BLANK="src/pages/BlankDashboard.tsx"
 echo "→ Creating ${BLANK}..."
 
 cat > "$BLANK" << 'DASHBOARD_EOF'
-import React from "react";
 import { RocketLaunchIcon } from "@heroicons/react/24/outline";
 import { EmptyState } from "@/components/library";
 
@@ -82,7 +87,10 @@ echo ""
 # ── 3. Update CommandCenter.tsx to use BlankDashboard ────────────────────────
 #    Preserves theme initialMode if previously customized.
 
-WRAPPER="src/components/pages/CommandCenter.tsx"
+# Ensure src/components/workspace directory exists
+mkdir -p src/components/workspace
+
+WRAPPER="src/components/workspace/CommandCenter.tsx"
 echo "→ Updating ${WRAPPER}..."
 
 # Extract existing initialMode from AppThemeProvider (default: "light")
@@ -99,7 +107,7 @@ cat > "$WRAPPER" << WRAPPER_EOF
 import AppThemeProvider from "@/components/library/theme/AppThemeProvider";
 import DataModeProvider from "@/components/library/data/DataModeProvider";
 import { Toast } from "@heroui/react";
-import BlankDashboard from "./BlankDashboard";
+import BlankDashboard from "../../pages/BlankDashboard";
 
 export default function CommandCenter() {
   return (
@@ -124,7 +132,7 @@ HOME="src/pages/Home.tsx"
 echo "→ Updating ${HOME}..."
 
 cat > "$HOME" << 'HOME_EOF'
-import CommandCenter from "../components/pages/CommandCenter";
+import CommandCenter from "../components/workspace/CommandCenter";
 
 export default function Home() {
 	return <CommandCenter />;
@@ -341,7 +349,7 @@ echo "║     /search   → Search (global search input)  ║"
 echo "║     Nav bar on Home + Search pages only        ║"
 echo "║                                                ║"
 echo "║   Start building:                              ║"
-echo "║     Edit src/components/pages/BlankDashboard.jsx║"
+echo "║     Edit src/pages/BlankDashboard.tsx          ║"
 echo "║     npm run dev                                 ║"
 echo "╚════════════════════════════════════════════════╝"
 echo ""