@dev.vinaypathak/global-route-search

v1.0.2

Published

10 months ago

A lightweight, framework-agnostic web component for searchable route navigation with keyboard shortcuts

0High
0Medium
0Low

dev.vinaypathak

global-route-search web-component navigation search routes keyboard-shortcuts typescript framework-agnostic

🚀 Global Route Search Web Component

A lightweight, framework-agnostic web component that provides a searchable route dialog accessible via keyboard shortcut (Cmd+K / Ctrl+K). Perfect for integrating into Angular, React, Vue, or any web application.

✨ Features

🔍 Global Search: Press Cmd+K (Mac) or Ctrl+K (Windows/Linux) from anywhere in your app
⚡ Fast Autocomplete: Real-time filtering of routes by name or path
🎯 Smart Navigation: Automatically prepends base URL to route paths
⌨️ Keyboard Friendly: Full keyboard navigation support
🎨 Modern UI: Clean, responsive design with smooth animations
🔒 Framework Agnostic: Works in any web application
📱 Responsive: Mobile-friendly design
🔄 Dynamic Routes: Update routes at runtime via attributes

📦 Installation

npm install @vinay_pathak/global-route-search

🚀 Quick Start

1. Include the Component

<script src="global-route-search.min.js"></script>

2. Initialize with Routes

const routes = [
    { label: "home", path: "seller/engage360" },
    { label: "orders", path: "seller/orders" },
    { label: "templates", path: "seller/channels/whatsapp/your-templates" }
];

// Create component instance
const routeSearch = document.createElement('global-route-search');
routeSearch.setAttribute('routes', JSON.stringify(routes));
document.body.appendChild(routeSearch);

3. Use the Component

Press Cmd+K (Mac) or Ctrl+K (Windows/Linux) to open the search dialog!

📋 API Reference

Component Attributes

| Attribute | Type | Description | Required | |-----------|------|-------------|----------| | routes | String | JSON string containing routes array | Yes |

Route Object Structure

{
    label: "Route Display Name",    // String - Human-readable route name
    path: "actual/route/path"       // String - URL path (without base URL)
}

Methods

| Method | Description | |--------|-------------| | setAttribute('routes', routesJson) | Update routes data | | remove() | Remove component from DOM |

🎮 Usage Examples

Basic HTML Integration

<!DOCTYPE html>
<html>
<head>
    <title>My App</title>
</head>
<body>
    <h1>Welcome to My App</h1>
    
    <!-- Include the component -->
    <script src="global-route-search.min.js"></script>
    
    <!-- Initialize -->
    <script>
        const routes = [
            { label: "Dashboard", path: "dashboard" },
            { label: "User Profile", path: "user/profile" },
            { label: "Settings", path: "settings" }
        ];
        
        const routeSearch = document.createElement('global-route-search');
        routeSearch.setAttribute('routes', JSON.stringify(routes));
        document.body.appendChild(routeSearch);
    </script>
</body>
</html>

Dynamic Route Updates

// Update routes at runtime
function updateRoutes(newRoutes) {
    const routeSearch = document.querySelector('global-route-search');
    if (routeSearch) {
        routeSearch.setAttribute('routes', JSON.stringify(newRoutes));
    }
}

// Example usage
updateRoutes([
    { label: "New Route", path: "new/route" },
    { label: "Another Route", path: "another/route" }
]);

🔧 Framework Integration

Angular

// app.component.ts
import { Component, OnInit } from '@angular/core';

@Component({
  selector: 'app-root',
  template: `<global-route-search [attr.routes]="routesJson"></global-route-search>`
})
export class AppComponent implements OnInit {
  routes = [
    { label: "Home", path: "home" },
    { label: "About", path: "about" }
  ];

  get routesJson(): string {
    return JSON.stringify(this.routes);
  }
}

React

// App.jsx
import React, { useEffect } from 'react';

function App() {
  useEffect(() => {
    const routes = [
      { label: "Home", path: "home" },
      { label: "About", path: "about" }
    ];
    
    const routeSearch = document.createElement('global-route-search');
    routeSearch.setAttribute('routes', JSON.stringify(routes));
    document.body.appendChild(routeSearch);
  }, []);

  return <div>My React App</div>;
}

Vue

<!-- App.vue -->
<template>
  <div id="app">
    <global-route-search :routes="routesJson" />
  </div>
</template>

<script>
export default {
  data() {
    return {
      routes: [
        { label: "Home", path: "home" },
        { label: "About", path: "about" }
      ]
    };
  },
  computed: {
    routesJson() {
      return JSON.stringify(this.routes);
    }
  }
};
</script>

⌨️ Keyboard Shortcuts

| Shortcut | Action | |----------|--------| | Cmd+K (Mac) / Ctrl+K (Win/Linux) | Open/close search dialog | | Escape | Close dialog | | ↑ / ↓ | Navigate through results | | Enter | Select highlighted result | | Click outside | Close dialog |

🎨 Customization

The component uses Shadow DOM for encapsulation, but you can customize the appearance by modifying the CSS variables or extending the component.

CSS Customization

// Extend the component to add custom styles
class CustomRouteSearch extends RouteSearchComponent {
    render() {
        // Add custom CSS or modify existing styles
        const customStyles = `
            .route-search-dialog {
                background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
                color: white;
            }
        `;
        
        // Call parent render method or implement custom rendering
        super.render();
    }
}

📱 Browser Support

✅ Chrome 67+
✅ Firefox 63+
✅ Safari 10.1+
✅ Edge 79+

🔍 How It Works

Global Listener: Component listens for Cmd+K / Ctrl+K globally
Route Filtering: Real-time filtering based on user input
Smart Navigation: Automatically constructs full URLs by prepending window.location.origin
Shadow DOM: Encapsulated styling and behavior
Event Handling: Proper cleanup and memory management

🚨 Important Notes

Base URL: Routes are automatically prepended with window.location.origin
Global Shortcut: The keyboard shortcut works globally across the entire application
Single Instance: Only one instance of the component should be active per page
Route Format: Ensure routes have both label and path properties

🐛 Troubleshooting

Common Issues

Shortcut not working: Ensure the component script is loaded before use
Routes not showing: Check that routes data is valid JSON
Navigation issues: Verify route paths are correct and don't include leading slashes

Debug Mode

// Enable debug logging
const routeSearch = document.querySelector('global-route-search');
if (routeSearch) {
    console.log('Routes:', routeSearch.routes);
    console.log('Component state:', routeSearch.isOpen);
}

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

📄 License

MIT License - feel free to use in your projects!

🆘 Support

If you encounter any issues or have questions:

Check the troubleshooting section
Review the integration examples
Open an issue on GitHub
Check browser console for errors

Happy coding! 🎉