cmp-standards 2.4.0 → 2.7.0

package/templates/workflows/internal-app.md

@@ -1,245 +1,245 @@
----
-description: "Create complex admin sections following the Internal App pattern (3+ tabs, mobile-first)"
----
-
-# Creating an Internal App Section
-
-Use this workflow when creating complex admin sections with 3+ tabs.
-
-**Examples**: EditEntity, EntitySettings, ComplexDashboard
-
----
-
-## Prerequisites
-
-- [ ] Component will have 3+ distinct sections/tabs
-- [ ] Mobile usage is important (used in field/on-the-go)
-- [ ] Complex data management required
-
----
-
-## Implementation Steps
-
-### 1. Check Qualification
-
-Ask yourself:
-- Does it have 3+ tabs? -> YES
-- Will it be used on mobile? -> YES
-- Is it data-heavy? -> YES
-
-If 2/3 are YES, proceed with Internal App pattern.
-
-### 2. Create File Structure
-
-```bash
-mkdir -p src/components/[domain]/edit-component
-mkdir -p src/components/[domain]/edit-component/components
-mkdir -p src/components/[domain]/edit-component/hooks
-mkdir -p src/components/[domain]/edit-component/sections
-mkdir -p src/components/[domain]/edit-component/logic
-```
-
-### 3. Implement Core Components
-
-#### Main Component
-```typescript
-import { useState } from 'react'
-import { useIsMobile } from '~/hooks/useIsMobile'
-import { MobileBottomNav } from './edit-component/components/MobileBottomNav'
-import { ErrorBoundary } from '~/components/shared/ErrorBoundary'
-
-type Section = 'GENERAL' | 'DETAILS' | 'ADVANCED'
-
-export const EditComponent = ({ id }: { id: string }) => {
-  const [section, setSection] = useState<Section>('GENERAL')
-  const isMobile = useIsMobile()
-
-  // Data fetching
-  const { data } = api.component.get.useQuery({ id })
-
-  // Keyboard shortcuts
-  useEffect(() => {
-    const handleKeyPress = (e: KeyboardEvent) => {
-      if (!(e.metaKey || e.ctrlKey)) return
-      // Add shortcuts...
-    }
-
-    window.addEventListener('keydown', handleKeyPress)
-    return () => window.removeEventListener('keydown', handleKeyPress)
-  }, [])
-
-  return (
-    <>
-      <ModalBase
-        variant="sidePanel"
-        customHeader={<Header isMobile={isMobile} />}
-      >
-        {/* Sections */}
-        {section === 'GENERAL' && (
-          <ErrorBoundary>
-            <GeneralSection data={data} />
-          </ErrorBoundary>
-        )}
-
-        {section === 'DETAILS' && (
-          <ErrorBoundary>
-            <DetailsSection data={data} />
-          </ErrorBoundary>
-        )}
-      </ModalBase>
-
-      {isMobile && (
-        <MobileBottomNav
-          section={section}
-          onSectionChange={setSection}
-        />
-      )}
-    </>
-  )
-}
-```
-
-#### MobileBottomNav
-```typescript
-const tabs = [
-  { id: 'GENERAL', label: t('General'), icon: <HomeIcon /> },
-  { id: 'DETAILS', label: t('Details'), icon: <ListIcon /> },
-  // Max 6 tabs
-]
-```
-
-### 4. Add Optional Enhancements
-
-**Progress Tracking:**
-```typescript
-// hooks/useCompletion.ts
-export function useCompletion(data) {
-  return useMemo(() => {
-    const checks = [
-      { key: 'name', value: !!data.name },
-      { key: 'description', value: !!data.description },
-      // ...
-    ]
-
-    const percentage = Math.round(
-      (checks.filter(c => c.value).length / checks.length) * 100
-    )
-
-    return { percentage }
-  }, [data])
-}
-```
-
-**Smart Suggestions:**
-```typescript
-// hooks/useNextSuggestion.ts
-export function useNextSuggestion(data) {
-  if (!data.name) return { message: 'Add a name', priority: 'high' }
-  if (!data.description) return { message: 'Add description', priority: 'medium' }
-  // ...
-}
-```
-
-### 5. Test Compliance
-
-```bash
-# Run compliance checker
-npm run lint:internal-app
-
-# Expected output for new component:
-# EditComponent......... 100% (7/7 criteria)
-```
-
-### 6. Manual Testing
-
-**Mobile** (Chrome DevTools -> Toggle device toolbar):
-- [ ] Bottom nav appears (< 768px)
-- [ ] All 3+ tabs clickable
-- [ ] Smooth section transitions
-- [ ] Icons render correctly
-- [ ] Active state visible
-
-**Desktop** (>= 768px):
-- [ ] Top tabs visible in header
-- [ ] Bottom nav hidden
-- [ ] Keyboard shortcuts work (Cmd+G, Cmd+D, etc)
-- [ ] Tab overflow scrolls if > 5 tabs
-
-**Error Handling:**
-- [ ] Inject error in one section
-- [ ] ErrorBoundary catches it
-- [ ] Other sections still work
-- [ ] "Try Again" button works
-
-**Accessibility:**
-- [ ] Screen reader announces tabs
-- [ ] All buttons have aria-label
-- [ ] Keyboard navigation works
-- [ ] Focus management correct
-
----
-
-## Common Issues & Solutions
-
-### Issue: "Component has 4 tabs but missing MobileBottomNav"
-
-**Solution:**
-1. Import MobileBottomNav
-2. Import useIsMobile hook
-3. Render conditionally: `{isMobile && <MobileBottomNav />}`
-4. Wrap in fragment: `<>...</>`
-
-### Issue: "Section not wrapped in ErrorBoundary"
-
-**Solution:**
-```typescript
-{section === 'GENERAL' && (
-  <ErrorBoundary>  // <- Add this
-    <GeneralSection />
-  </ErrorBoundary>  // <- And this
-)}
-```
-
-### Issue: Bottom nav not showing on mobile
-
-**Check:**
-1. Viewport is < 768px
-2. `isMobile` returns true (console.log it)
-3. Z-index is 50 or higher
-4. No CSS `display: none` overrides
-
----
-
-## Performance Tips
-
-1. **Lazy load sections:**
-   ```typescript
-   const AdvancedSection = lazy(() => import('./sections/AdvancedSection'))
-   ```
-
-2. **Prefetch on hover** (desktop):
-   ```typescript
-   onMouseEnter={() => void ctx.component.getData.prefetch({ id })}
-   ```
-
-3. **Memoize calculations:**
-   ```typescript
-   const processedData = useMemo(() => process(rawData), [rawData])
-   ```
-
----
-
-## Verification Checklist
-
-Before marking complete:
-
-- [ ] Lint check passes
-- [ ] TypeScript check passes
-- [ ] Manual mobile testing complete
-- [ ] Manual desktop testing complete
-- [ ] Accessibility verified
-- [ ] Documentation updated
-
----
-
-**Status**: Production Ready
+---
+description: "Create complex admin sections following the Internal App pattern (3+ tabs, mobile-first)"
+---
+
+# Creating an Internal App Section
+
+Use this workflow when creating complex admin sections with 3+ tabs.
+
+**Examples**: EditEntity, EntitySettings, ComplexDashboard
+
+---
+
+## Prerequisites
+
+- [ ] Component will have 3+ distinct sections/tabs
+- [ ] Mobile usage is important (used in field/on-the-go)
+- [ ] Complex data management required
+
+---
+
+## Implementation Steps
+
+### 1. Check Qualification
+
+Ask yourself:
+- Does it have 3+ tabs? -> YES
+- Will it be used on mobile? -> YES
+- Is it data-heavy? -> YES
+
+If 2/3 are YES, proceed with Internal App pattern.
+
+### 2. Create File Structure
+
+```bash
+mkdir -p src/components/[domain]/edit-component
+mkdir -p src/components/[domain]/edit-component/components
+mkdir -p src/components/[domain]/edit-component/hooks
+mkdir -p src/components/[domain]/edit-component/sections
+mkdir -p src/components/[domain]/edit-component/logic
+```
+
+### 3. Implement Core Components
+
+#### Main Component
+```typescript
+import { useState } from 'react'
+import { useIsMobile } from '~/hooks/useIsMobile'
+import { MobileBottomNav } from './edit-component/components/MobileBottomNav'
+import { ErrorBoundary } from '~/components/shared/ErrorBoundary'
+
+type Section = 'GENERAL' | 'DETAILS' | 'ADVANCED'
+
+export const EditComponent = ({ id }: { id: string }) => {
+  const [section, setSection] = useState<Section>('GENERAL')
+  const isMobile = useIsMobile()
+
+  // Data fetching
+  const { data } = api.component.get.useQuery({ id })
+
+  // Keyboard shortcuts
+  useEffect(() => {
+    const handleKeyPress = (e: KeyboardEvent) => {
+      if (!(e.metaKey || e.ctrlKey)) return
+      // Add shortcuts...
+    }
+
+    window.addEventListener('keydown', handleKeyPress)
+    return () => window.removeEventListener('keydown', handleKeyPress)
+  }, [])
+
+  return (
+    <>
+      <ModalBase
+        variant="sidePanel"
+        customHeader={<Header isMobile={isMobile} />}
+      >
+        {/* Sections */}
+        {section === 'GENERAL' && (
+          <ErrorBoundary>
+            <GeneralSection data={data} />
+          </ErrorBoundary>
+        )}
+
+        {section === 'DETAILS' && (
+          <ErrorBoundary>
+            <DetailsSection data={data} />
+          </ErrorBoundary>
+        )}
+      </ModalBase>
+
+      {isMobile && (
+        <MobileBottomNav
+          section={section}
+          onSectionChange={setSection}
+        />
+      )}
+    </>
+  )
+}
+```
+
+#### MobileBottomNav
+```typescript
+const tabs = [
+  { id: 'GENERAL', label: t('General'), icon: <HomeIcon /> },
+  { id: 'DETAILS', label: t('Details'), icon: <ListIcon /> },
+  // Max 6 tabs
+]
+```
+
+### 4. Add Optional Enhancements
+
+**Progress Tracking:**
+```typescript
+// hooks/useCompletion.ts
+export function useCompletion(data) {
+  return useMemo(() => {
+    const checks = [
+      { key: 'name', value: !!data.name },
+      { key: 'description', value: !!data.description },
+      // ...
+    ]
+
+    const percentage = Math.round(
+      (checks.filter(c => c.value).length / checks.length) * 100
+    )
+
+    return { percentage }
+  }, [data])
+}
+```
+
+**Smart Suggestions:**
+```typescript
+// hooks/useNextSuggestion.ts
+export function useNextSuggestion(data) {
+  if (!data.name) return { message: 'Add a name', priority: 'high' }
+  if (!data.description) return { message: 'Add description', priority: 'medium' }
+  // ...
+}
+```
+
+### 5. Test Compliance
+
+```bash
+# Run compliance checker
+npm run lint:internal-app
+
+# Expected output for new component:
+# EditComponent......... 100% (7/7 criteria)
+```
+
+### 6. Manual Testing
+
+**Mobile** (Chrome DevTools -> Toggle device toolbar):
+- [ ] Bottom nav appears (< 768px)
+- [ ] All 3+ tabs clickable
+- [ ] Smooth section transitions
+- [ ] Icons render correctly
+- [ ] Active state visible
+
+**Desktop** (>= 768px):
+- [ ] Top tabs visible in header
+- [ ] Bottom nav hidden
+- [ ] Keyboard shortcuts work (Cmd+G, Cmd+D, etc)
+- [ ] Tab overflow scrolls if > 5 tabs
+
+**Error Handling:**
+- [ ] Inject error in one section
+- [ ] ErrorBoundary catches it
+- [ ] Other sections still work
+- [ ] "Try Again" button works
+
+**Accessibility:**
+- [ ] Screen reader announces tabs
+- [ ] All buttons have aria-label
+- [ ] Keyboard navigation works
+- [ ] Focus management correct
+
+---
+
+## Common Issues & Solutions
+
+### Issue: "Component has 4 tabs but missing MobileBottomNav"
+
+**Solution:**
+1. Import MobileBottomNav
+2. Import useIsMobile hook
+3. Render conditionally: `{isMobile && <MobileBottomNav />}`
+4. Wrap in fragment: `<>...</>`
+
+### Issue: "Section not wrapped in ErrorBoundary"
+
+**Solution:**
+```typescript
+{section === 'GENERAL' && (
+  <ErrorBoundary>  // <- Add this
+    <GeneralSection />
+  </ErrorBoundary>  // <- And this
+)}
+```
+
+### Issue: Bottom nav not showing on mobile
+
+**Check:**
+1. Viewport is < 768px
+2. `isMobile` returns true (console.log it)
+3. Z-index is 50 or higher
+4. No CSS `display: none` overrides
+
+---
+
+## Performance Tips
+
+1. **Lazy load sections:**
+   ```typescript
+   const AdvancedSection = lazy(() => import('./sections/AdvancedSection'))
+   ```
+
+2. **Prefetch on hover** (desktop):
+   ```typescript
+   onMouseEnter={() => void ctx.component.getData.prefetch({ id })}
+   ```
+
+3. **Memoize calculations:**
+   ```typescript
+   const processedData = useMemo(() => process(rawData), [rawData])
+   ```
+
+---
+
+## Verification Checklist
+
+Before marking complete:
+
+- [ ] Lint check passes
+- [ ] TypeScript check passes
+- [ ] Manual mobile testing complete
+- [ ] Manual desktop testing complete
+- [ ] Accessibility verified
+- [ ] Documentation updated
+
+---
+
+**Status**: Production Ready