@schandlergarcia/sf-web-components 1.9.61 → 1.9.62

package/CHANGELOG.md

@@ -5,6 +5,24 @@ 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).
 
+## [1.9.62] - 2026-04-01
+
+### Added
+- **CLAUDE.md** - Comprehensive guidance for working with the package in Claude Code
+  - Package overview and purpose
+  - Critical explanation of two UI contexts (outer app vs command center)
+  - Architecture and directory structure
+  - Key conventions (component naming, theme hook, data hook)
+  - Development workflow and pre-publish checks
+  - Postinstall and reset script behavior
+  - Important files guide
+  - Common issues and solutions
+  - Testing checklist
+  - Version history summary
+  - Now included in published package (added to files array)
+
+This file provides essential context when opening sf-web-components as a standalone Claude Code project, explaining the architecture, conventions, and common pitfalls (like UIButton vs Button confusion).
+
 ## [1.9.61] - 2026-04-01
 
 ### Updated

package/CLAUDE.md

@@ -0,0 +1,258 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with the sf-web-components package.
+
+## Package Overview
+
+**@schandlergarcia/sf-web-components** is an npm package that provides:
+
+1. **React component library** - Pre-built UI components for Salesforce Web Applications
+2. **Templates** - Page templates (Home, Search, NotFound, BlankDashboard) and config templates (routes.tsx, vite.config.ts, dataStrategy.ts)
+3. **Automation** - Postinstall script that sets up consuming projects automatically
+4. **Documentation** - `.a4drules` skills and features for AI-assisted development
+5. **Sample data** - Engine Travel sample data and pre-built GraphQL schema
+6. **Scripts** - Reset scripts, validation scripts, schema generation
+
+**Primary use case:** Building Salesforce Web Applications with React, specifically for:
+- Outer app pages (search, navigation) using shadcn/ui + Tailwind
+- Command Center dashboards using custom library components + HeroUI
+
+## Architecture
+
+### Two UI Contexts (CRITICAL)
+
+The package supports **two distinct UI contexts** that must NOT be mixed:
+
+#### 1. Outer App Context
+- **Files:** `src/pages/Home.tsx`, `src/pages/Search.tsx`, `src/pages/NotFound.tsx` (installed from templates)
+- **Rendered in:** AppLayout wrapper (standard React Router routes)
+- **Components:** shadcn/ui from `@/components/ui/`
+  - `Button` from `@/components/ui/button`
+  - `Input` from `@/components/ui/input`
+  - etc.
+- **Icons:** Lucide React (`lucide-react`)
+- **Styling:** Neutral shadcn theme (slate colors, no Engine branding)
+- **File type:** `.tsx`
+
+#### 2. Command Center Context
+- **Files:** Dashboard pages in `src/pages/` (e.g., BlankDashboard, EngineDashboard)
+- **Rendered in:** CommandCenter wrapper with `.heroui-scope` class
+- **Components:** Library components from `@/components/library`
+  - `UIButton` from `@/components/library/ui/UIButton`
+  - `UIInput` from `@/components/library/ui/UIInput`
+  - `MetricCard`, `ChartCard`, `ListCard`, `TableCard`, etc.
+- **Icons:** Heroicons (`@heroicons/react`)
+- **Styling:** Engine brand colors (teal #5BC8C8, coral, orange) inside `.heroui-scope`
+- **File type:** `.jsx` or `.tsx`
+
+**Common mistake:** Using UIButton/UIInput in outer app pages or shadcn Button/Input in command center dashboards. Check `.a4drules/features/pre-code-checklist.md` for validation rules.
+
+### Package Structure
+
+```
+sf-web-components/
+├── src/
+│   ├── components/
+│   │   ├── library/           # Command center components (MetricCard, ChartCard, etc.)
+│   │   │   ├── cards/
+│   │   │   ├── charts/
+│   │   │   ├── ui/            # UIButton, UIInput, etc.
+│   │   │   ├── theme/         # AppThemeProvider, useThemeMode
+│   │   │   ├── data/          # useDataSource, DataModeProvider
+│   │   │   └── index.jsx      # Barrel export
+│   │   └── workspace/         # CommandRegistry, ComponentRegistry
+│   ├── templates/
+│   │   ├── pages/             # Home.tsx.template, Search.tsx.template, etc.
+│   │   ├── config/            # routes.tsx.template, vite.config.ts.template
+│   │   ├── lib/               # dataStrategy.ts.template
+│   │   └── workspace/         # CommandCenter.tsx.template
+│   ├── lib/                   # Utilities (utils.ts)
+│   └── styles/                # global.css with Engine brand tokens
+├── scripts/
+│   ├── postinstall.mjs        # Runs after npm install in consuming projects
+│   ├── reset-command-center.sh
+│   ├── validate-dashboard.sh
+│   └── verify-consistency.sh
+├── data/
+│   ├── engine-sample-data.js
+│   ├── schema.graphql
+│   └── engine-command-center-prd.md
+└── .a4drules/
+    ├── features/              # Dashboard rules, engine-dashboard-rule, etc.
+    ├── skills/                # component-library, command-center-builder, etc.
+    ├── troubleshooting/       # Common issues and solutions
+    ├── validation-requirements.md
+    ├── webapp-data.md
+    └── webapp-ui.md
+```
+
+## Key Conventions
+
+### Component Naming
+- **Library components** (command center): `UIButton`, `UIInput`, `MetricCard`, `ChartCard`
+- **shadcn components** (outer app): `Button`, `Input`, `Card` from `@/components/ui/`
+
+### Theme Hook
+- **Correct:** `import { useThemeMode } from "@/components/library/theme/AppThemeProvider"`
+- **Wrong:** `import useAppTheme from ...` (does not exist)
+- **Usage:** `const { mode, toggle } = useThemeMode();`
+
+### Data Hook
+- **Pattern:** Use `useDataSource` for instant loading with sample data cache
+- **Example:**
+  ```javascript
+  import useDataSource from "@/components/library/data/useDataSource";
+  
+  const travelers = useDataSource({
+    sample: SAMPLE_TRAVELERS,
+    live: liveTravelers ?? []
+  });
+  ```
+- **Configuration:** `src/lib/dataStrategy.ts` controls `ENABLE_SAMPLE_DATA_CACHE`
+
+### File Extensions
+- **Outer app pages:** `.tsx`
+- **Command center dashboards:** `.jsx` or `.tsx` (`.jsx` preferred per dashboard rules)
+
+## Working with the Package
+
+### Development Workflow
+
+1. **Make changes** to components, templates, or documentation
+2. **Update version:** `npm version patch` (or minor/major)
+3. **Update CHANGELOG.md** with:
+   - Version number
+   - Date
+   - What changed and why
+   - Context for the change
+4. **Build:** `npm run build`
+5. **Verify:** `npm run verify` (checks consistency)
+6. **Publish:** `npm publish` (runs pre-publish checks automatically)
+
+### Pre-Publish Checks
+
+The `scripts/pre-publish-check.sh` runs automatically before publishing and verifies:
+1. Consistency between code, docs, and templates
+2. CHANGELOG.md has entry for current version
+3. Component naming conventions (UIButton.tsx exists, Button.tsx doesn't in library/ui/)
+4. Build succeeds
+5. Documentation files exist
+6. package.json files array includes necessary directories
+
+### Postinstall Behavior
+
+When a project installs this package, `scripts/postinstall.mjs` automatically:
+
+1. **Copies component library** to `src/components/library/`
+2. **Copies lib utilities** to `src/lib/`
+3. **Copies types** to `src/types/`
+4. **Copies workspace files** to `src/components/workspace/`
+5. **Installs page templates** to `src/pages/` (Home.tsx, Search.tsx, NotFound.tsx, BlankDashboard.tsx)
+6. **Updates imports** in existing files (changes package imports to local `@/components/library` imports)
+7. **Copies sample data** to `src/data/engine-sample-data.js`
+8. **Copies schema** to root `schema.graphql`
+9. **Copies PRD** to root `engine-command-center-prd.md`
+10. **Installs config files** (routes.tsx, vite.config.ts, dataStrategy.ts) if they don't exist
+11. **Adds npm scripts** to package.json (reset:command-center, validate:dashboard, graphql:schema:sample)
+12. **Copies .a4drules** to project root for AI assistant discoverability
+
+**Important:** Templates are **always overwritten** to ensure latest versions, except for config files (vite.config.ts, dataStrategy.ts) which only install if missing.
+
+### Reset Script
+
+The `scripts/reset-command-center.sh` provides a clean baseline for projects:
+
+- Removes custom dashboard pages
+- Restores BlankDashboard.tsx
+- Updates CommandCenter.tsx to render BlankDashboard
+- Restores Home.tsx with Account Search page
+- Restores Search.tsx placeholder
+- Updates routes.tsx to include Home, /accounts, and /accounts/:recordId
+- Updates appLayout.tsx with nav bar
+- Clears Vite cache
+- Restores Engine-branded global.css
+- Restores sample data and schema
+
+## Important Files
+
+### CHANGELOG.md
+Complete history of all changes. ALWAYS update when making changes. Include:
+- What changed
+- Why it changed
+- Context for the change
+- Impact on consuming projects
+
+### .a4drules/
+AI assistant documentation. Key files:
+- `features/engine-dashboard-rule.md` - How to build Engine Travel Command Center
+- `features/command-center-dashboard-rule.md` - Dashboard development rules
+- `features/pre-code-checklist.md` - Pre-implementation validation
+- `skills/component-library/` - Component API reference
+- `validation-requirements.md` - Validation rules
+- `webapp-data.md` - Data access patterns (GraphQL, REST, SDK usage)
+- `webapp-ui.md` - UI platform rules
+
+### data/engine-command-center-prd.md
+Product Requirements Document for Engine Travel Command Center. Defines:
+- Product overview and users
+- Brand tokens (Engine teal #5BC8C8, etc.)
+- Layout structure (visualization-hero pattern)
+- Component sections and data model
+- Phase-by-phase build instructions
+
+### src/components/library/theme/AppThemeProvider.jsx
+Theme provider with dark mode toggle. Exports:
+- **Default:** `AppThemeProvider` component
+- **Named:** `useThemeMode` hook
+
+### src/components/library/data/useDataSource.js
+Hook for sample/live data switching via `ENABLE_SAMPLE_DATA_CACHE` flag.
+
+## Common Issues
+
+### TypeScript Errors
+If you see TypeScript errors about missing exports:
+1. Check the actual file to see what's exported
+2. Don't trust TypeScript's suggestions blindly (it may suggest wrong import patterns)
+3. Refer to `.a4drules/skills/component-library/SKILL.md` for correct import patterns
+
+### Component Confusion
+If agents mix up UIButton (library) vs Button (shadcn):
+1. Check `.a4drules/features/pre-code-checklist.md` for validation rules
+2. Outer app pages should NEVER import from `@/components/library`
+3. Command center dashboards should NEVER import from `@/components/ui/`
+
+### Routes Not Working
+If routes show 404:
+1. Check routes.tsx imports match installed file locations
+2. Home should point to `./pages/Home` (not `__examples__`)
+3. Accounts should point to `./features/object-search/__examples__/pages/AccountSearch`
+4. Make sure `handle.showNavBar: true` is set for pages that need nav
+
+### Missing Nav Bar
+Routes need `handle: { showInNavigation: true, showNavBar: true }` for nav bar to appear.
+
+## Testing
+
+Before publishing:
+1. Test in a real project (reactapp4, vibes3, etc.)
+2. Run `npm install @schandlergarcia/sf-web-components@latest`
+3. Verify postinstall behavior
+4. Check templates are correct
+5. Verify .a4drules are accessible
+6. Test reset script: `npm run reset:command-center`
+7. Test validation: `npm run validate:dashboard`
+
+## Version History
+
+See CHANGELOG.md for complete history. Recent major changes:
+- v1.9.55 - Fixed UIButton/Button confusion in templates
+- v1.9.56 - Fixed reset script 404 errors
+- v1.9.57 - Restored "Browse All Accounts" button
+- v1.9.58 - Fixed reset routes pointing to wrong Home file
+- v1.9.59 - Restored navigation bar (showNavBar flag)
+- v1.9.60-61 - Synced .a4drules and PRD from reactapp4
+
+## Current Version
+
+Run `node -p "require('./package.json').version"` to get current version.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schandlergarcia/sf-web-components",
-  "version": "1.9.61",
+  "version": "1.9.62",
   "description": "Reusable Salesforce web components library with Tailwind CSS v4 and shadcn/ui",
   "type": "module",
   "main": "./dist/index.js",
@@ -38,6 +38,7 @@
     "CONTRIBUTING.md",
     "ARCHITECTURE.md",
     "QUICK-REFERENCE.md",
+    "CLAUDE.md",
     ".a4drules"
   ],
   "scripts": {