Navigation Quick Reference & Implementation Guide

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

Navigation Documentation Index: For an overview of all navigation documentation, see NAVIGATION_GUIDE_INDEX.md
Navigation Standard: For complete navigation standards and policies, see NAVIGATION_STANDARD.md

​

Phase 1: Foundation (Weeks 1-2)

​

Task 1.1: Add Sub-Module Visual Indicators (Desktop)

1. Add visual badge/indicator for sub-module groups
2. Show sub-module description on hover
3. Style sub-module groups differently

// In NavGroupWithOverview component
{group.isSubModule && (
  <Badge variant="secondary" className="ml-auto text-xs">
    Sub-Module
  </Badge>
)}

• Sub-modules have visual indicator in desktop sidebar
• Description shows on hover/focus
• Visual distinction is clear but not overwhelming

​

Task 1.2: Enhance Mobile Menu Sheet for Sub-Modules

1. Show sub-modules prominently in module section
2. Add sub-module quick actions
3. Improve sub-module context display

// Add sub-module section before "All Modules"
{module.navGroups?.some(g => g.isSubModule) && (
  <div className="space-y-2">
    <h3 className="text-sm font-medium">Sub-Modules</h3>
    {module.navGroups
      .filter(g => g.isSubModule)
      .map(subModule => (
        <SubModuleCard 
          key={subModule.id}
          subModule={subModule}
          parentModule={module}
        />
      ))}
  </div>
)}

• Sub-modules visible in mobile menu
• Quick actions accessible
• Clear parent-child relationship

​

Task 1.3: Document Navigation Standards

1. Add navigation pattern decision tree
2. Document when to use navItems vs. navGroups vs. sub-modules
3. Add visual examples

• Decision tree documented
• Examples for each pattern
• Guidelines for module creators

​

Phase 2: HR Optimization (Weeks 3-4)

​

Task 2.1: Make HR Groups Collapsible with Smart Defaults

1. Make all HR groups collapsible (not just 5+)
2. Default: Open “People Management” and current sub-module
3. Remember collapsed state per user

// Update useCollapsible logic
const useCollapsible = visibleNavGroups.length >= 3 || 
  module.id === 'hr'; // HR always uses collapsible

// Smart defaults
const [isOpen, setIsOpen] = useState(
  hasActiveItem || 
  group.defaultOpen || 
  (module.id === 'hr' && group.id === 'people-management') ||
  false
);

• All HR groups are collapsible
• Smart defaults work correctly
• State persists per user (future: localStorage)

​

Task 2.2: Add Sub-Module Quick Actions to HR Overview

1. Show sub-module quick actions in group header
2. Add module-level quick actions section
3. Make quick actions accessible from parent view

// In NavGroupWithOverview, show quick actions when group is sub-module
{group.isSubModule && group.quickActions && (
  <div className="flex gap-1 px-3 py-1">
    {group.quickActions.map(action => (
      <Button key={action.route} variant="outline" size="sm">
        <ActionIcon className="h-3 w-3" />
        {action.label}
      </Button>
    ))}
  </div>
)}

• Quick actions visible in group header
• Quick actions work correctly
• Mobile-friendly touch targets

​

Task 2.3: Improve Mobile Sub-Module Discovery

1. Add “Enter Sub-Module” buttons in mobile menu
2. Show sub-module preview cards
3. Improve sub-module context in header

// Add sub-module cards in module section
{module.navGroups
  .filter(g => g.isSubModule)
  .map(subModule => (
    <div key={subModule.id} className="border rounded-lg p-3">
      <div className="flex items-center gap-2 mb-2">
        <SubModuleIcon className="h-4 w-4" />
        <span className="font-medium">{subModule.label}</span>
      </div>
      <p className="text-xs text-muted-foreground mb-2">
        {subModule.description}
      </p>
      <Button 
        variant="outline" 
        size="sm"
        onClick={() => handleNavigation(subModule.overviewRoute)}
      >
        Enter {subModule.label}
      </Button>
    </div>
  ))}

• Sub-modules discoverable in mobile menu
• Clear entry points
• Preview information helpful

​

Task 2.4: Add HR Sub-Module to Mobile Bottom Nav Config

1. Add HR sub-module shortcuts to available shortcuts
2. Allow users to customize which sub-module appears
3. Update default shortcuts if needed

// Add to AVAILABLE_SHORTCUTS
{
  id: "hr-compliance",
  label: "Compliance",
  icon: ShieldCheck,
  route: "/hr/compliance",
  permission: "hr.compliance.view",
  category: "sub-module",
  parentModule: "hr",
  subModuleId: "compliance",
},

• HR sub-modules available in bottom nav config
• Users can customize
• Permissions respected

​

Phase 3: Cross-Module Consistency (Weeks 5-6)

​

Task 3.1: Update Module Flyout for Sub-Modules

1. Show sub-modules with visual distinction
2. Include sub-module quick actions
3. Add “Enter Sub-Module” action

// In CollapsibleNavGroupSection
{group.isSubModule && (
  <div className="flex items-center gap-2 px-3 py-1 bg-primary/5 rounded">
    <Badge variant="secondary" className="text-xs">Sub-Module</Badge>
    {group.quickActions && (
      <div className="flex gap-1 ml-auto">
        {group.quickActions.slice(0, 2).map(action => (
          <Button key={action.route} variant="ghost" size="sm">
            <ActionIcon className="h-3 w-3" />
          </Button>
        ))}
      </div>
    )}
  </div>
)}

• Sub-modules visible in flyout
• Quick actions accessible
• Visual distinction clear

​

Task 3.2: Standardize Mobile Menu Sheet

1. Consistent layout for all modules
2. Sub-module section standardized
3. Improved search includes sub-modules

// Standardize module rendering
const renderModule = (module: ModuleDefinition) => {
  const hasSubModules = module.navGroups?.some(g => g.isSubModule);
  
  return (
    <div className="space-y-2">
      <ModuleHeader module={module} />
      {hasSubModules && (
        <SubModulesSection 
          subModules={module.navGroups.filter(g => g.isSubModule)}
        />
      )}
      <ModuleNavItems module={module} />
    </div>
  );
};

• Consistent layout across modules
• Sub-modules always visible when present
• Search works for sub-modules

​

Task 3.3: Review and Align All Modules

1. Review each module against standards
2. Align navigation patterns
3. Ensure consistency

• Uses appropriate pattern (navItems vs. navGroups vs. sub-modules)
• Groups are logical and scannable
• Sub-modules have overviewRoute and quickActions
• Permissions are correct
• Mobile shortcuts configured (if applicable)

• HR (already optimized in Phase 2)
• RH
• FA
• FW
• LO
• FM
• GR

​

Phase 4: Advanced Features (Weeks 7-8)

​

Task 4.1: Navigation Customization UI

1. Create navigation customization component
2. Allow pinning favorite sub-modules
3. Customize group order
4. Hide unused groups

// New component structure
export function NavigationCustomizer() {
  const { currentModule } = useNavigation();
  const [pinnedItems, setPinnedItems] = useState<string[]>([]);
  const [hiddenGroups, setHiddenGroups] = useState<string[]>([]);
  
  // Save preferences to user profile
  const savePreferences = async () => {
    // Store in pf_user_preferences table
  };
  
  return (
    <Dialog>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Customize Navigation</DialogTitle>
        </DialogHeader>
        <div className="space-y-4">
          <PinnedItemsSection />
          <GroupOrderSection />
          <HiddenGroupsSection />
        </div>
      </DialogContent>
    </Dialog>
  );
}

• Users can customize navigation
• Preferences persist
• Mobile and desktop supported

​

Task 4.2: Enhance Global Search with Sub-Modules

1. Include sub-modules in search results
2. Show sub-module context in results
3. Quick navigation to sub-modules

// In search results
const searchResults = useMemo(() => {
  const allResults = [
    ...modules,
    ...modules.flatMap(m => 
      m.navGroups
        ?.filter(g => g.isSubModule)
        .map(sub => ({
          ...sub,
          parentModule: m.name,
          category: 'sub-module',
        })) || []
    ),
    // ... other results
  ];
  
  return filterResults(allResults, query);
}, [query]);

• Sub-modules appear in search
• Context is clear
• Navigation works correctly

​

Task 4.3: Usage Analytics Integration

1. Track navigation usage
2. Identify pain points
3. Create analytics dashboard

export function useNavigationAnalytics() {
  const trackNavigation = (event: NavigationEvent) => {
    // Send to analytics service
    analytics.track('navigation', {
      module: event.module,
      subModule: event.subModule,
      route: event.route,
      timestamp: Date.now(),
    });
  };
  
  return { trackNavigation };
}

• Navigation events tracked
• Analytics dashboard created
• Privacy-compliant (no PHI)

​

Testing Checklist

​

Desktop Testing

• All modules render correctly
• Sub-modules have visual indicators
• Collapsible groups work
• Quick actions accessible
• Keyboard navigation works
• Screen reader compatible

​

Mobile Testing

• Mobile menu shows sub-modules
• Touch targets meet 44px minimum
• Sub-module navigation works
• Breadcrumbs display correctly
• Bottom nav customizable
• Safe area insets respected

​

Cross-Module Testing

• All modules follow standards
• Navigation patterns consistent
• Permissions respected
• Performance acceptable

​

Rollout Strategy

​

Phase 1 Rollout

1. Deploy to staging
2. Internal testing (1 week)
3. Beta users (1 week)
4. Production release

​

Phase 2 Rollout

1. Deploy HR improvements to staging
2. HR team testing (1 week)
3. All users (gradual rollout)

​

Phase 3 Rollout

1. Deploy all module improvements
2. User communication
3. Training materials
4. Support documentation

​

Phase 4 Rollout

1. Feature flags for customization
2. Opt-in beta
3. Gradual rollout
4. Analytics monitoring

​

Success Criteria

​

Phase 1

• Sub-modules visually distinct
• Mobile menu improved
• Standards documented

​

Phase 2

• HR navigation optimized
• User feedback positive
• No regression in other modules

​

Phase 3

• All modules consistent
• Navigation patterns standardized
• User experience improved

​

Phase 4

• Customization available
• Search enhanced
• Analytics providing insights

​

Support & Documentation

​

User Documentation

• Navigation guide for users
• Sub-module explanation
• Customization tutorial
• FAQ updates

​

Developer Documentation

• Navigation standards updated
• Module creation guide
• Sub-module implementation guide
• API documentation

​

Training Materials

• Video tutorials
• Screenshots
• Step-by-step guides
• Best practices