@schandlergarcia/sf-web-components 1.9.48 → 1.9.52

package/.a4drules/troubleshooting/graphql-introspection-failure.md

@@ -0,0 +1,286 @@
+# GraphQL Schema Introspection Failure
+
+## Problem
+
+When running `npm run graphql:schema`, the introspection query fails with an error like:
+
+```
+Cannot invoke FieldDataType.equals(Object) because 
+the return value of Field.getDataType() is null
+```
+
+This is an **org-level bug** where at least one field in the Salesforce org has a null data type, which breaks the `__schema` introspection query.
+
+## What's Broken
+
+- ❌ Generating `schema.graphql` from org introspection
+- ❌ Full schema with all org objects and fields
+- ❌ Some IDE autocomplete features that query the org directly
+
+## What Still Works
+
+- ✅ **Regular GraphQL queries** — Queries execute normally despite introspection failure
+- ✅ All CRUD operations via GraphQL
+- ✅ The Data SDK (`createDataSDK()`)
+- ✅ UI API GraphQL endpoint (`/services/data/v{ver}/graphql`)
+- ✅ **Schema generation from sample data** (see Solution below)
+
+**Key insight:** Introspection is just metadata about the schema. It doesn't affect actual query execution.
+
+## Solution: Pre-built Schema (Already in Repo)
+
+The `schema.graphql` file is **already checked into the repo** at the project root. It was generated from the sample data file and includes all Engine objects.
+
+**You don't need to generate anything** — the schema is ready to use.
+
+**What this provides:**
+- ✅ `exploring-webapp-graphql-schema` skill works normally
+- ✅ `generating-webapp-graphql-read-query` skill works normally
+- ✅ `using-webapp-graphql` skill works normally
+- ✅ IDE autocomplete and validation
+- ✅ GraphQL codegen
+- ✅ Normal Phase 3 workflow without manual workarounds
+- ✅ Works in CI/CD without org access
+
+**Schema contents:**
+- Contact (travelers with custom fields)
+- Trip__c, Flight__c, Booking__c, Disruption__c, Rebooking_Action__c, Travel_Policy__c
+- All fields from `src/data/engine-sample-data.js`
+
+## Regenerating the Schema (Optional)
+
+If you need to update the schema (e.g., after adding new fields to sample data):
+
+```bash
+# From the webapp directory
+npm run graphql:schema:sample
+```
+
+This regenerates `schema.graphql` from the current sample data file. Then commit the updated schema to git.
+
+## Fallback: Copy Working Query Patterns (Manual)
+
+Since introspection fails but queries work, you can implement GraphQL features by copying working patterns from elsewhere in the codebase.
+
+### Step 1: Find a Working Query
+
+Look for existing GraphQL implementations (e.g., Account search, Contact queries in other features):
+
+```bash
+cd force-app/main/default/webapplications/reactapp4
+grep -r "uiapi {" src/
+```
+
+### Step 2: Copy the Pattern
+
+The working pattern for UI API GraphQL queries:
+
+```typescript
+import { createDataSDK, gql } from "@salesforce/sdk-data";
+
+const GET_TRIPS = gql`
+  query GetTrips {
+    uiapi {
+      query {
+        Trip__c(first: 50) {
+          edges {
+            node {
+              Id
+              Trip_Name__c @optional { value }
+              Origin_City__c @optional { value }
+              Destination_City__c @optional { value }
+              Contact__c @optional { value }
+              Start_Date__c @optional { value }
+              End_Date__c @optional { value }
+              Status__c @optional { value }
+              Total_Cost__c @optional { value }
+              In_Policy__c @optional { value }
+              Has_Disruption__c @optional { value }
+            }
+          }
+        }
+      }
+    }
+  }
+`;
+```
+
+**Critical elements:**
+- `uiapi { query { ... } }` wrapper
+- Object name matches Salesforce API name (e.g., `Trip__c`, `Contact`)
+- `@optional` directive on ALL fields except `Id` (for FLS resilience)
+- Nested field access: `FieldName { value }` for most fields
+- Lookup fields: `RelatedObject__c { Name { value } }`
+
+### Step 3: Implement Hooks
+
+Create custom hooks using the Data SDK pattern:
+
+```typescript
+import { useState, useEffect } from "react";
+import { createDataSDK } from "@salesforce/sdk-data";
+
+export function useTrips() {
+  const [data, setData] = useState<any[] | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    let mounted = true;
+
+    async function fetchData() {
+      try {
+        const sdk = await createDataSDK();
+        const response = await sdk.graphql?.(GET_TRIPS);
+
+        if (!mounted) return;
+
+        if (response?.errors?.length) {
+          throw new Error(response.errors.map((e: any) => e.message).join("; "));
+        }
+
+        const edges = response?.data?.uiapi?.query?.Trip__c?.edges ?? [];
+        const trips = edges.map((edge: any) => ({
+          Id: edge.node.Id,
+          Trip_Name__c: edge.node.Trip_Name__c?.value ?? null,
+          Origin_City__c: edge.node.Origin_City__c?.value ?? null,
+          // ... map all fields with optional chaining
+        }));
+
+        setData(trips);
+        setError(null);
+      } catch (err) {
+        if (mounted) {
+          setError(err instanceof Error ? err : new Error(String(err)));
+        }
+      } finally {
+        if (mounted) {
+          setLoading(false);
+        }
+      }
+    }
+
+    fetchData();
+
+    return () => {
+      mounted = false;
+    };
+  }, []);
+
+  return { data, loading, error };
+}
+```
+
+### Step 4: Get Field Names from Sample Data
+
+The sample data file already has real Salesforce field names. Read `src/data/engine-sample-data.js` to see which fields exist:
+
+```javascript
+// File: src/data/engine-sample-data.js
+export const TRIPS = [
+  {
+    Id: "a00xx000001",
+    Trip_Name__c: "Q1 Sales Conference - SF",
+    Origin_City__c: "New York",
+    Destination_City__c: "San Francisco",
+    // ... etc
+  }
+];
+```
+
+Copy these exact field names into your GraphQL query.
+
+### Step 5: Test Your Queries
+
+Create a test script to verify queries work:
+
+```javascript
+// scripts/test-engine-query.mjs
+import { getOrgInfo } from '@salesforce/webapp-experimental/app';
+
+async function testQuery(query, objectName) {
+  const { rawInstanceUrl, apiVersion, accessToken } = await getOrgInfo();
+  
+  const response = await fetch(
+    `${rawInstanceUrl}/services/data/v${apiVersion}/graphql`,
+    {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        'Content-Type': 'application/json',
+        'X-Chatter-Entity-Encoding': 'false',
+      },
+      body: JSON.stringify({ query }),
+    }
+  );
+  
+  const result = await response.json();
+  
+  if (result.errors) {
+    console.error(`❌ ${objectName} query failed:`, result.errors);
+    return false;
+  }
+  
+  console.log(`✅ ${objectName} query succeeded`);
+  console.log(`   Records found: ${result.data?.uiapi?.query?.[objectName]?.edges?.length}`);
+  return true;
+}
+
+// Test your queries
+await testQuery(`query { uiapi { query { Trip__c(first: 1) { edges { node { Id } } } } } }`, 'Trip__c');
+```
+
+Run: `node scripts/test-engine-query.mjs`
+
+## For Agents Building the Dashboard
+
+**The schema.graphql file is already in the repo.** Just use the GraphQL skills normally:
+
+1. `exploring-webapp-graphql-schema` — Looks up field names
+2. `generating-webapp-graphql-read-query` — Creates queries
+3. `using-webapp-graphql` — Implements hooks
+
+No schema generation needed during Phase 3.
+
+## For Developers Adding Fields
+
+If you add new fields to `src/data/engine-sample-data.js`, regenerate the schema:
+
+```bash
+cd force-app/main/default/webapplications/reactapp4
+npm run graphql:schema:sample
+git add ../../../../../../schema.graphql
+git commit -m "Update schema with new fields"
+```
+
+## Decision Tree for Schema Updates
+
+**Do you need to update schema.graphql?**
+
+- ❌ Building dashboard from existing sample data? → No, use existing schema
+- ✅ Added new fields to sample data? → Run `npm run graphql:schema:sample`
+- ✅ Added new custom objects? → Update generation script first, then regenerate
+- ✅ Want to try org introspection? → Run `npm run graphql:schema` (may fail)
+
+## Prevention
+
+This is an org-level bug that can't be prevented from the web app side. The org admin would need to identify and fix the field(s) with null data types. However, this workaround allows development to continue without waiting for org fixes.
+
+## Related Files
+
+- `.a4drules/features/engine-dashboard-rule.md` — Phase 3 implementation with workaround steps
+- `engine-command-center-prd.md` — Phase 3 prompt updated to include fallback approach
+- `scripts/get-graphql-schema.mjs` — The script that runs introspection (will fail with this bug)
+- `scripts/test-engine-query.mjs` — Test script to verify queries work despite introspection failure
+
+## Success Indicators
+
+You've successfully worked around the issue when:
+
+- ✅ All custom hooks return data correctly (`{ data, loading, error }`)
+- ✅ Dashboard displays live Salesforce data
+- ✅ No GraphQL-related errors in browser console
+- ✅ Test script shows all queries succeed
+- ✅ Loading and error states work properly
+
+The fact that schema.graphql doesn't exist is fine — it's only needed for introspection-based tooling, not for runtime queries.

package/.a4drules/validation-requirements.md

@@ -0,0 +1,211 @@
+---
+paths:
+  - "**/pages/*.tsx"
+  - "**/components/workspace/*.tsx"
+---
+
+# Validation Requirements (MANDATORY)
+
+This file defines the mandatory validation process for all command center dashboards.
+
+## The Validator
+
+The validator is a shell script at `node_modules/@schandlergarcia/sf-web-components/scripts/validate-dashboard.sh` that automatically checks for common mistakes.
+
+**Location to run:** Always run from the webapp directory:
+
+```bash
+cd force-app/main/default/webapplications/reactapp4
+npm run validate:dashboard
+```
+
+## When to Run
+
+**Run the validator after EVERY significant change:**
+- After creating a new dashboard page
+- After adding components
+- After updating styles
+- After changing imports
+- Before committing code
+- Before reporting a phase/task as complete
+
+**Frequency:** If in doubt, run it. It takes <1 second.
+
+## Zero Errors Required
+
+The validator MUST show zero errors before:
+- Proceeding to the next build phase
+- Reporting a task as complete
+- Committing code
+- Deploying
+
+**Do NOT:**
+- Dismiss errors as "justified" or "acceptable"
+- Skip validation "because you're sure it's correct"
+- Report work as complete with validator errors
+- Proceed to the next phase with errors
+
+**Every error has a fix.** The fix is usually switching to a library component.
+
+## What the Validator Checks
+
+1. **Hand-rolled HTML cards** — Detects `<div className="bg-white border rounded-[10px]">` patterns that should be library cards
+2. **Forbidden colors** — Flags `text-black`, `text-white`, `bg-black` (use slate scale)
+3. **Inline styles** — Detects `style={{}}` and `<style>` tags (use Tailwind)
+4. **Missing useDataSource** — Checks that data uses sample/live mode pattern
+5. **Grid layouts** — Flags `grid-cols-5` or higher (max is 4 KPIs per row)
+6. **Position fixed** — Checks that `position: fixed` uses `createPortal`
+7. **shadcn imports** — Detects imports from `@/components/ui/` (use library)
+8. **Lucide imports** — Detects imports from `lucide-react` (use Heroicons)
+9. **File extension** — Ensures `.tsx` not `.jsx` (TypeScript project)
+10. **Dashboard navigation** — Detects `<nav>` elements (handled by AppLayout)
+11. **Missing space-y** — Checks for proper section spacing
+
+## Common Errors and Fixes
+
+### "Hand-rolled card detected"
+
+**Error:** `bg-white border rounded-[10px] shadow-sm` pattern found
+**Fix:** Wrap content in a library card component
+
+```tsx
+// ❌ Wrong
+<div className="bg-white border rounded-[10px] shadow-sm p-6">
+  <h2>Active Travelers</h2>
+  {travelers.map(...)}
+</div>
+
+// ✅ Correct
+<ListCard title="Active Travelers" items={travelers} />
+
+// ✅ Also correct (for custom content)
+<WidgetCard
+  sections={[{
+    id: "travelers",
+    content: <div>{travelers.map(...)}</div>
+  }]}
+/>
+```
+
+### "Forbidden color"
+
+**Error:** `text-white`, `text-black`, or `bg-black` detected
+**Fix:** Use slate scale
+
+```tsx
+// ❌ Wrong
+className="text-white bg-black"
+
+// ✅ Correct
+className="text-slate-50 dark:text-slate-900 bg-slate-900 dark:bg-slate-950"
+```
+
+### "shadcn import detected"
+
+**Error:** `from '@/components/ui/button'` or similar
+**Fix:** Use library equivalent
+
+```tsx
+// ❌ Wrong
+import { Button } from '@/components/ui/button';
+
+// ✅ Correct
+import { UIButton } from '@/components/library';
+```
+
+### "Missing useDataSource"
+
+**Error:** Hardcoded data array without mode switching
+**Fix:** Use `useDataSource` pattern
+
+```tsx
+// ❌ Wrong
+const travelers = SAMPLE_TRAVELERS;  // always sample
+
+// ✅ Correct
+const travelers = useDataSource({ sample: SAMPLE_TRAVELERS, live: liveTravelers });
+```
+
+### "Inline style detected"
+
+**Error:** `style={{}}` or `<style>` tag found
+**Fix:** Use Tailwind classes or global.css
+
+```tsx
+// ❌ Wrong
+<div style={{ padding: '20px', backgroundColor: '#fff' }}>
+
+// ✅ Correct
+<div className="p-5 bg-white dark:bg-slate-900">
+```
+
+### "Grid exceeds 4 columns"
+
+**Error:** `grid-cols-5` or higher detected
+**Fix:** Max 4 KPIs per row — split across multiple rows
+
+```tsx
+// ❌ Wrong
+<div className="grid grid-cols-5 gap-3">  // 5 KPIs
+
+// ✅ Correct
+<div className="grid grid-cols-4 gap-3">  // 4 KPIs
+<div className="grid grid-cols-1 gap-3 sm:grid-cols-1">  // 1 KPI on second row
+```
+
+## Error Priority
+
+If the validator reports multiple errors, fix them in this order:
+
+1. **File extension** (`.jsx` → `.tsx`) — affects everything
+2. **Imports** (shadcn/Lucide → library/Heroicons) — structural
+3. **Hand-rolled cards** (→ library components) — most common
+4. **Forbidden colors** (→ slate scale) — visual
+5. **Other errors** (useDataSource, inline styles, etc.)
+
+## Success Criteria
+
+The validator is successful when it outputs:
+
+```
+✅ All checks passed
+Dashboard is ready
+```
+
+Any other output means there are errors that MUST be fixed.
+
+## Integration with Build Phases
+
+For the Engine Travel Command Center (and all 4-phase dashboards):
+
+- **End of Phase 1:** Run validator, fix errors → proceed to Phase 2
+- **End of Phase 2:** Run validator, fix errors → proceed to Phase 3
+- **End of Phase 3:** Run validator, fix errors → proceed to Phase 4
+- **End of Phase 4:** Run validator, fix errors → DONE
+
+## Do Not Run These Instead
+
+**Do NOT run:**
+- `npm run build` — This runs TypeScript checking which has known issues with platform-only Salesforce packages. The validator is sufficient for dashboard validation.
+- `tsc` or `tsc -b` — Same issue as above
+- `npm run lint` — This is for ESLint, not dashboard validation
+
+**Only run:**
+- `npm run validate:dashboard` — The correct validator for dashboards
+- `npm run dev` — To test the dashboard in the browser after validation passes
+
+## When to Ask for Help
+
+If you see a validator error you don't understand:
+1. Read the error message carefully
+2. Check this file for the fix pattern
+3. Check `.a4drules/features/command-center-dashboard-rule.md` for the rule
+4. Check the component-library skill for the correct component API
+
+If still stuck, ask: "The validator reports [error]. I tried [fix]. What's the correct approach?"
+
+## The Golden Rule
+
+**Validator errors are not suggestions — they are requirements.**
+
+Zero errors is not optional. Zero errors is the definition of "done".