npm - @flxgde/gigamenu - Versions diffs - 0.0.1 - Mend

@flxgde/gigamenu 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/.github/workflows/publish.yml +31 -0
package/README.md +127 -0
package/ng-package.json +8 -0
package/package.json +39 -0
package/src/lib/frecency.service.ts +185 -0
package/src/lib/gigamenu-templates.directive.ts +178 -0
package/src/lib/gigamenu.component.html +170 -0
package/src/lib/gigamenu.component.ts +305 -0
package/src/lib/gigamenu.service.ts +143 -0
package/src/lib/types.ts +101 -0
package/src/public-api.ts +6 -0
package/tsconfig.json +14 -0
package/tsconfig.lib.json +12 -0
package/tsconfig.lib.prod.json +6 -0

package/.github/workflows/publish.yml ADDED Viewed

@@ -0,0 +1,31 @@
+name: Build & Publish
+on:
+  push:
+    branches: [main]
+    tags:
+      - 'v*'
+jobs:
+  build:
+    runs-on: self-hosted
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+      - name: Install dependencies
+        run: npm ci
+      - name: Build
+        run: npm run build
+      - name: Publish
+        if: startsWith(github.ref, 'refs/tags/v')
+        working-directory: dist/gigamenu
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md ADDED Viewed

@@ -0,0 +1,127 @@
+# Gigamenu
+A keyboard-driven command palette menu for Angular applications. Inspired by VS Code's Command Palette, Spotlight, and Linear's command menu.
+## Features
+- Keyboard shortcuts: `Ctrl/Cmd+K` and `/` (when no input is focused)
+- Auto-discovery of routes from Angular Router
+- Manual command registration API
+- Full keyboard navigation (arrow keys, Enter, Escape)
+- Fuzzy search filtering
+- Dark mode support
+- Tailwind CSS styling
+## Installation
+```bash
+npm install gigamenu
+```
+## Usage
+### 1. Import the component
+```typescript
+import { Component, inject, OnInit } from '@angular/core';
+import { GigamenuComponent, GigamenuService } from 'gigamenu';
+@Component({
+  selector: 'app-root',
+  imports: [GigamenuComponent],
+  template: `
+    <router-outlet />
+    <gm-gigamenu />
+  `,
+})
+export class App implements OnInit {
+  private readonly gigamenu = inject(GigamenuService);
+  ngOnInit(): void {
+    // Auto-discover routes from Angular Router
+    this.gigamenu.discoverRoutes();
+  }
+}
+```
+### 2. Register custom commands
+```typescript
+this.gigamenu.registerCommand({
+  id: 'cmd:toggle-dark',
+  label: 'Toggle Dark Mode',
+  description: 'Switch between light and dark theme',
+  icon: '🌙',
+  keywords: ['theme', 'dark', 'light'],
+  action: () => document.documentElement.classList.toggle('dark'),
+});
+```
+### 3. Register custom pages
+```typescript
+this.gigamenu.registerPage({
+  id: 'page:dashboard',
+  label: 'Dashboard',
+  path: '/dashboard',
+  description: 'Go to the main dashboard',
+});
+```
+## API
+### GigamenuService
+| Method | Description |
+|--------|-------------|
+| `open()` | Open the menu |
+| `close()` | Close the menu |
+| `toggle()` | Toggle menu visibility |
+| `discoverRoutes(routes?)` | Auto-discover pages from Angular Router |
+| `registerCommand(command)` | Register a custom command |
+| `registerPage(page)` | Register a custom page |
+| `registerItem(item)` | Register a generic menu item |
+| `unregisterItem(id)` | Remove an item by ID |
+| `configure(config)` | Update configuration |
+### Configuration
+```typescript
+interface GigamenuConfig {
+  placeholder?: string;      // Search input placeholder
+  maxResults?: number;       // Maximum items to show (default: 10)
+  autoDiscoverRoutes?: boolean; // Auto-discover on init
+}
+```
+### Types
+```typescript
+interface GigamenuItem {
+  id: string;
+  label: string;
+  description?: string;
+  icon?: string;
+  keywords?: string[];
+  category: 'page' | 'command';
+  action: () => void;
+}
+```
+## Keyboard Shortcuts
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl/Cmd+K` | Open menu |
+| `/` | Open menu (when no input focused) |
+| `↑` / `↓` | Navigate items |
+| `Enter` | Execute selected item |
+| `Escape` | Close menu |
+## Styling
+Gigamenu uses Tailwind CSS and supports dark mode via the `dark` class on `<html>`.
+## License
+MIT

package/ng-package.json ADDED Viewed

@@ -0,0 +1,8 @@
+{
+  "$schema": "node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "dist/gigamenu",
+  "lib": {
+    "entryFile": "src/public-api.ts"
+  },
+  "assets": ["README.md"]
+}

package/package.json ADDED Viewed

@@ -0,0 +1,39 @@
+{
+  "name": "@flxgde/gigamenu",
+  "version": "0.0.1",
+  "description": "A keyboard-driven command palette menu for Angular applications",
+  "keywords": [
+    "angular",
+    "command-palette",
+    "keyboard-navigation",
+    "menu",
+    "spotlight",
+    "ctrl-k"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flxgde/gigamenu"
+  },
+  "homepage": "https://github.com/flxgde/gigamenu#readme",
+  "bugs": {
+    "url": "https://github.com/flxgde/gigamenu/issues"
+  },
+  "scripts": {
+    "build": "ng-packagr",
+    "build:prod": "ng-packagr -c tsconfig.lib.prod.json"
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "@angular/common": "^21.0.0",
+    "@angular/core": "^21.0.0",
+    "@angular/router": "^21.0.0"
+  },
+  "devDependencies": {
+    "ng-packagr": "^21.0.0",
+    "@angular/compiler": "^21.0.0",
+    "@angular/compiler-cli": "^21.0.0",
+    "typescript": "~5.9.2"
+  }
+}

package/src/lib/frecency.service.ts ADDED Viewed

@@ -0,0 +1,185 @@
+import { Injectable, PLATFORM_ID, Inject } from '@angular/core';
+import { isPlatformBrowser } from '@angular/common';
+interface FrecencyEntry {
+  itemId: string;
+  count: number;
+  lastUsed: number;
+}
+interface FrecencyData {
+  [searchTerm: string]: FrecencyEntry[];
+}
+const STORAGE_KEY = 'gigamenu_frecency';
+const GLOBAL_KEY = '__global__';
+const MAX_ENTRIES_PER_TERM = 10;
+const MAX_TERMS = 100;
+const DECAY_FACTOR = 0.9;
+@Injectable({ providedIn: 'root' })
+export class FrecencyService {
+  private data: FrecencyData = {};
+  private readonly isBrowser: boolean;
+  constructor(@Inject(PLATFORM_ID) platformId: object) {
+    this.isBrowser = isPlatformBrowser(platformId);
+    this.load();
+  }
+  /**
+   * Record that an item was selected for a given search term.
+   */
+  recordSelection(searchTerm: string, itemId: string): void {
+    // Always record to global for overall frecency
+    this.recordToKey(GLOBAL_KEY, itemId);
+    // Also record to specific search term if provided
+    const normalizedTerm = this.normalizeTerm(searchTerm);
+    if (normalizedTerm) {
+      this.recordToKey(normalizedTerm, itemId);
+    }
+    this.pruneAndSave();
+  }
+  private recordToKey(key: string, itemId: string): void {
+    if (!this.data[key]) {
+      this.data[key] = [];
+    }
+    const entries = this.data[key];
+    const existing = entries.find((e) => e.itemId === itemId);
+    if (existing) {
+      existing.count++;
+      existing.lastUsed = Date.now();
+    } else {
+      entries.push({
+        itemId,
+        count: 1,
+        lastUsed: Date.now(),
+      });
+    }
+    // Keep only top entries
+    this.data[key] = entries
+      .sort((a, b) => this.calculateScore(b) - this.calculateScore(a))
+      .slice(0, MAX_ENTRIES_PER_TERM);
+  }
+  /**
+   * Get frecency scores for items matching a search term.
+   * Returns a map of itemId -> score (higher is better).
+   */
+  getScores(searchTerm: string): Map<string, number> {
+    const scores = new Map<string, number>();
+    const normalizedTerm = this.normalizeTerm(searchTerm);
+    // If no search term, return global scores
+    if (!normalizedTerm) {
+      const globalEntries = this.data[GLOBAL_KEY];
+      if (globalEntries) {
+        for (const entry of globalEntries) {
+          scores.set(entry.itemId, this.calculateScore(entry));
+        }
+      }
+      return scores;
+    }
+    // Exact match for search term
+    const exactEntries = this.data[normalizedTerm];
+    if (exactEntries) {
+      for (const entry of exactEntries) {
+        const score = this.calculateScore(entry);
+        scores.set(entry.itemId, score);
+      }
+    }
+    // Prefix matches (for partial typing)
+    for (const [term, entries] of Object.entries(this.data)) {
+      if (term !== GLOBAL_KEY && term !== normalizedTerm && term.startsWith(normalizedTerm)) {
+        for (const entry of entries) {
+          const currentScore = scores.get(entry.itemId) ?? 0;
+          // Prefix matches get reduced weight
+          const prefixScore = this.calculateScore(entry) * 0.5;
+          scores.set(entry.itemId, Math.max(currentScore, prefixScore));
+        }
+      }
+    }
+    return scores;
+  }
+  /**
+   * Get the most likely item for a search term (for auto-selection).
+   * Returns itemId if there's a strong match, null otherwise.
+   */
+  getTopMatch(searchTerm: string): string | null {
+    const normalizedTerm = this.normalizeTerm(searchTerm);
+    if (!normalizedTerm) return null;
+    const entries = this.data[normalizedTerm];
+    if (!entries || entries.length === 0) return null;
+    const topEntry = entries[0];
+    const score = this.calculateScore(topEntry);
+    // Only auto-select if strong confidence (used multiple times recently)
+    if (topEntry.count >= 2 && score > 5) {
+      return topEntry.itemId;
+    }
+    return null;
+  }
+  private calculateScore(entry: FrecencyEntry): number {
+    const ageInHours = (Date.now() - entry.lastUsed) / (60 * 60 * 24);
+    const recencyScore = Math.pow(DECAY_FACTOR, ageInHours);
+    return entry.count * recencyScore;
+  }
+  private normalizeTerm(term: string): string {
+    return term.toLowerCase().trim();
+  }
+  private load(): void {
+    if (!this.isBrowser) return;
+    try {
+      const stored = localStorage.getItem(STORAGE_KEY);
+      if (stored) {
+        this.data = JSON.parse(stored);
+      }
+    } catch {
+      this.data = {};
+    }
+  }
+  private pruneAndSave(): void {
+    if (!this.isBrowser) return;
+    // Prune old terms if we have too many
+    const terms = Object.keys(this.data);
+    if (terms.length > MAX_TERMS) {
+      const termScores = terms.map((term) => ({
+        term,
+        maxScore: Math.max(...this.data[term].map((e) => this.calculateScore(e))),
+      }));
+      termScores.sort((a, b) => b.maxScore - a.maxScore);
+      const keepTerms = new Set(termScores.slice(0, MAX_TERMS).map((t) => t.term));
+      for (const term of terms) {
+        if (!keepTerms.has(term)) {
+          delete this.data[term];
+        }
+      }
+    }
+    try {
+      localStorage.setItem(STORAGE_KEY, JSON.stringify(this.data));
+    } catch {
+      // Storage full or unavailable
+    }
+  }
+}

package/src/lib/gigamenu-templates.directive.ts ADDED Viewed

@@ -0,0 +1,178 @@
+import { Directive, TemplateRef, inject } from '@angular/core';
+import { GigamenuItem } from './types';
+/**
+ * Context provided to the item template.
+ */
+export interface GigamenuItemContext {
+  /** The menu item being rendered */
+  $implicit: GigamenuItem;
+  /** The index of the item in the filtered list */
+  index: number;
+  /** Whether this item is currently selected */
+  selected: boolean;
+}
+/**
+ * Context provided to the empty template.
+ */
+export interface GigamenuEmptyContext {
+  /** The current search query */
+  $implicit: string;
+}
+/**
+ * Context provided to the header template.
+ */
+export interface GigamenuHeaderContext {
+  /** The current full query */
+  $implicit: string;
+  /** The search term (before separator) */
+  searchTerm: string;
+  /** The arguments (after separator) */
+  args: string;
+  /** Callback to update the query */
+  onQueryChange: (value: string) => void;
+  /** Callback for keydown events */
+  onKeydown: (event: KeyboardEvent) => void;
+  /** Placeholder text */
+  placeholder: string;
+}
+/**
+ * Context provided to the footer template.
+ */
+export interface GigamenuFooterContext {
+  /** Number of filtered items */
+  $implicit: number;
+  /** Total number of items */
+  total: number;
+}
+/**
+ * Template directive for customizing menu item rendering.
+ *
+ * @example
+ * ```html
+ * <gm-gigamenu>
+ *   <ng-template gmItem let-item let-selected="selected" let-index="index">
+ *     <div [class.active]="selected">
+ *       {{ item.label }}
+ *     </div>
+ *   </ng-template>
+ * </gm-gigamenu>
+ * ```
+ */
+@Directive({
+  selector: '[gmItem]',
+  standalone: true,
+})
+export class GigamenuItemTemplate {
+  readonly template = inject<TemplateRef<GigamenuItemContext>>(TemplateRef);
+}
+/**
+ * Template directive for customizing empty state rendering.
+ *
+ * @example
+ * ```html
+ * <gm-gigamenu>
+ *   <ng-template gmEmpty let-query>
+ *     <div>No results for "{{ query }}"</div>
+ *   </ng-template>
+ * </gm-gigamenu>
+ * ```
+ */
+@Directive({
+  selector: '[gmEmpty]',
+  standalone: true,
+})
+export class GigamenuEmptyTemplate {
+  readonly template = inject<TemplateRef<GigamenuEmptyContext>>(TemplateRef);
+}
+/**
+ * Template directive for customizing header/search input rendering.
+ *
+ * @example
+ * ```html
+ * <gm-gigamenu>
+ *   <ng-template gmHeader let-query let-onQueryChange="onQueryChange" let-onKeydown="onKeydown">
+ *     <input [value]="query" (input)="onQueryChange($event.target.value)" (keydown)="onKeydown($event)" />
+ *   </ng-template>
+ * </gm-gigamenu>
+ * ```
+ */
+@Directive({
+  selector: '[gmHeader]',
+  standalone: true,
+})
+export class GigamenuHeaderTemplate {
+  readonly template = inject<TemplateRef<GigamenuHeaderContext>>(TemplateRef);
+}
+/**
+ * Template directive for customizing footer rendering.
+ *
+ * @example
+ * ```html
+ * <gm-gigamenu>
+ *   <ng-template gmFooter let-count let-total="total">
+ *     <div>Showing {{ count }} of {{ total }} items</div>
+ *   </ng-template>
+ * </gm-gigamenu>
+ * ```
+ */
+@Directive({
+  selector: '[gmFooter]',
+  standalone: true,
+})
+export class GigamenuFooterTemplate {
+  readonly template = inject<TemplateRef<GigamenuFooterContext>>(TemplateRef);
+}
+/**
+ * Template directive for customizing the entire panel/dialog container.
+ * When provided, replaces the entire default panel structure.
+ *
+ * @example
+ * ```html
+ * <gm-gigamenu>
+ *   <ng-template gmPanel let-items let-query="query" let-selectedIndex="selectedIndex">
+ *     <div class="my-custom-panel">
+ *       <!-- Custom implementation -->
+ *     </div>
+ *   </ng-template>
+ * </gm-gigamenu>
+ * ```
+ */
+export interface GigamenuPanelContext {
+  /** Filtered items to display */
+  $implicit: GigamenuItem[];
+  /** Current full query */
+  query: string;
+  /** The search term (before separator) */
+  searchTerm: string;
+  /** The arguments (after separator) */
+  args: string;
+  /** Currently selected index */
+  selectedIndex: number;
+  /** Callback to execute an item */
+  executeItem: (item: GigamenuItem) => void;
+  /** Callback to update selection */
+  setSelectedIndex: (index: number) => void;
+  /** Callback to update query */
+  setQuery: (query: string) => void;
+  /** Callback to close the menu */
+  close: () => void;
+  /** Placeholder text from config */
+  placeholder: string;
+}
+@Directive({
+  selector: '[gmPanel]',
+  standalone: true,
+})
+export class GigamenuPanelTemplate {
+  readonly template = inject<TemplateRef<GigamenuPanelContext>>(TemplateRef);
+}

package/src/lib/gigamenu.component.html ADDED Viewed

@@ -0,0 +1,170 @@
+@if (service.isOpen()) {
+<div
+  class="fixed inset-0 z-50 flex items-start justify-center pt-[15vh]"
+  (click)="onBackdropClick($event)"
+>
+  <div class="fixed inset-0 bg-black/50 backdrop-blur-sm"></div>
+  <!-- Custom panel template -->
+  @if (panelTemplate(); as pt) {
+    <ng-container
+      [ngTemplateOutlet]="pt.template"
+      [ngTemplateOutletContext]="getPanelContext()"
+    ></ng-container>
+  } @else {
+  <!-- Default panel -->
+  <div
+    class="relative z-10 w-full max-w-xl overflow-hidden rounded-xl border border-neutral-200 bg-white shadow-2xl dark:border-neutral-700 dark:bg-neutral-900"
+    role="dialog"
+    aria-modal="true"
+    aria-label="Command menu"
+  >
+    <!-- Header -->
+    @if (headerTemplate(); as ht) {
+      <ng-container
+        [ngTemplateOutlet]="ht.template"
+        [ngTemplateOutletContext]="getHeaderContext()"
+      ></ng-container>
+    } @else {
+    <div class="flex items-center border-b border-neutral-200 px-4 dark:border-neutral-700">
+      <svg
+        class="h-5 w-5 text-neutral-400"
+        fill="none"
+        stroke="currentColor"
+        viewBox="0 0 24 24"
+      >
+        <path
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          stroke-width="2"
+          d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"
+        />
+      </svg>
+      <div class="relative flex-1">
+        <!-- Styled overlay for syntax highlighting -->
+        <div
+          class="pointer-events-none absolute inset-0 flex items-center px-3 py-4 text-base"
+          aria-hidden="true"
+        >
+          <span class="text-neutral-900 dark:text-neutral-100">{{ searchTerm() }}</span>@if (args()) {<span class="text-neutral-900 dark:text-neutral-100">{{ service.config().argSeparator }}</span><span class="text-purple-600 dark:text-purple-400">{{ args() }}</span>}
+        </div>
+        <!-- Transparent input on top -->
+        <input
+          #searchInput
+          type="text"
+          [placeholder]="service.config().placeholder"
+          [value]="query()"
+          (input)="onQueryChange($event)"
+          (keydown)="onInputKeydown($event)"
+          class="relative z-10 w-full bg-transparent px-3 py-4 text-base text-transparent caret-neutral-900 placeholder-neutral-400 outline-none dark:caret-neutral-100"
+        />
+      </div>
+      <kbd
+        class="rounded border border-neutral-200 bg-neutral-100 px-1.5 py-0.5 text-xs text-neutral-500 dark:border-neutral-600 dark:bg-neutral-800 dark:text-neutral-400"
+      >
+        ESC
+      </kbd>
+    </div>
+    }
+    <!-- Items list -->
+    <div #listContainer class="max-h-80 overflow-y-auto p-2">
+      @if (filteredItems().length === 0) {
+        <!-- Empty state -->
+        @if (emptyTemplate(); as et) {
+          <ng-container
+            [ngTemplateOutlet]="et.template"
+            [ngTemplateOutletContext]="getEmptyContext()"
+          ></ng-container>
+        } @else {
+        <div class="px-3 py-8 text-center text-neutral-500">
+          No results found
+        </div>
+        }
+      } @else {
+        @for (item of filteredItems(); track item.id; let i = $index) {
+          <!-- Custom item template -->
+          @if (itemTemplate(); as it) {
+            <ng-container
+              [ngTemplateOutlet]="it.template"
+              [ngTemplateOutletContext]="getItemContext(item, i)"
+            ></ng-container>
+          } @else {
+          <!-- Default item -->
+          <button
+            type="button"
+            (click)="executeItem(item)"
+            (mouseenter)="selectedIndex.set(i)"
+            [attr.data-index]="i"
+            [class]="
+            'flex w-full items-center gap-3 rounded-lg px-3 py-2.5 text-left transition-colors ' +
+            (selectedIndex() === i
+            ? 'bg-neutral-100 dark:bg-neutral-800'
+            : 'hover:bg-neutral-50 dark:hover:bg-neutral-800/50')
+            "
+          >
+            @if (item.iconClass) {
+            <i [class]="item.iconClass + ' text-lg text-neutral-600 dark:text-neutral-300'"></i>
+            } @else if (item.icon) {
+            <span class="text-lg">{{ item.icon }}</span>
+            } @else {
+            <span
+              class="flex h-6 w-6 items-center justify-center rounded bg-neutral-200 text-xs font-medium text-neutral-600 dark:bg-neutral-700 dark:text-neutral-300"
+            >
+              {{ item.category === 'page' ? 'P' : 'C' }}
+            </span>
+            }
+            <div class="flex-1 min-w-0">
+              <div class="truncate font-medium text-neutral-900 dark:text-neutral-100">
+                {{ item.label }}
+              </div>
+              @if (item.description) {
+              <div class="truncate text-sm text-neutral-500 dark:text-neutral-400">
+                {{ item.description }}
+              </div>
+              }
+            </div>
+            <span
+              class="rounded-full px-2 py-0.5 text-xs"
+              [class]="
+              item.category === 'page'
+              ? 'bg-blue-100 text-blue-700 dark:bg-blue-900/30 dark:text-blue-400'
+              : 'bg-purple-100 text-purple-700 dark:bg-purple-900/30 dark:text-purple-400'
+              "
+            >
+              {{ item.category }}
+            </span>
+          </button>
+          }
+        }
+      }
+    </div>
+    <!-- Footer -->
+    @if (footerTemplate(); as ft) {
+      <ng-container
+        [ngTemplateOutlet]="ft.template"
+        [ngTemplateOutletContext]="getFooterContext()"
+      ></ng-container>
+    } @else {
+    <div
+      class="flex items-center justify-between border-t border-neutral-200 px-4 py-2 text-xs text-neutral-500 dark:border-neutral-700"
+    >
+      <div class="flex items-center gap-3">
+        <span class="flex items-center gap-1">
+          <kbd class="rounded border border-neutral-300 bg-neutral-100 px-1 dark:border-neutral-600 dark:bg-neutral-800">↑</kbd>
+          <kbd class="rounded border border-neutral-300 bg-neutral-100 px-1 dark:border-neutral-600 dark:bg-neutral-800">↓</kbd>
+          navigate
+        </span>
+        <span class="flex items-center gap-1">
+          <kbd class="rounded border border-neutral-300 bg-neutral-100 px-1 dark:border-neutral-600 dark:bg-neutral-800">↵</kbd>
+          select
+        </span>
+      </div>
+      <span>gigamenu</span>
+    </div>
+    }
+  </div>
+  }
+</div>
+}

package/src/lib/gigamenu.component.ts ADDED Viewed

@@ -0,0 +1,305 @@
+import {
+  Component,
+  signal,
+  computed,
+  effect,
+  ElementRef,
+  viewChild,
+  contentChild,
+  HostListener,
+  PLATFORM_ID,
+  Inject,
+  TemplateRef,
+} from '@angular/core';
+import { isPlatformBrowser, NgTemplateOutlet } from '@angular/common';
+import { GigamenuService } from './gigamenu.service';
+import { FrecencyService } from './frecency.service';
+import { GigamenuItem } from './types';
+import {
+  GigamenuItemTemplate,
+  GigamenuEmptyTemplate,
+  GigamenuHeaderTemplate,
+  GigamenuFooterTemplate,
+  GigamenuPanelTemplate,
+  GigamenuItemContext,
+  GigamenuEmptyContext,
+  GigamenuHeaderContext,
+  GigamenuFooterContext,
+  GigamenuPanelContext,
+} from './gigamenu-templates.directive';
+@Component({
+  selector: 'gm-gigamenu',
+  standalone: true,
+  imports: [NgTemplateOutlet],
+  templateUrl: 'gigamenu.component.html',
+  styles: `
+    :host {
+      display: contents;
+    }
+  `,
+})
+export class GigamenuComponent {
+  private readonly searchInput = viewChild<ElementRef<HTMLInputElement>>('searchInput');
+  private readonly listContainer = viewChild<ElementRef<HTMLDivElement>>('listContainer');
+  private readonly isBrowser: boolean;
+  // Template queries
+  protected readonly itemTemplate = contentChild(GigamenuItemTemplate);
+  protected readonly emptyTemplate = contentChild(GigamenuEmptyTemplate);
+  protected readonly headerTemplate = contentChild(GigamenuHeaderTemplate);
+  protected readonly footerTemplate = contentChild(GigamenuFooterTemplate);
+  protected readonly panelTemplate = contentChild(GigamenuPanelTemplate);
+  protected readonly query = signal('');
+  protected readonly selectedIndex = signal(0);
+  /** Parsed search term (before first separator) */
+  protected readonly searchTerm = computed(() => {
+    const q = this.query();
+    const separator = this.service.config().argSeparator ?? ' ';
+    const sepIndex = q.indexOf(separator);
+    if (sepIndex === -1) return q;
+    return q.substring(0, sepIndex);
+  });
+  /** Parsed arguments (after first separator) */
+  protected readonly args = computed(() => {
+    const q = this.query();
+    const separator = this.service.config().argSeparator ?? ' ';
+    const sepIndex = q.indexOf(separator);
+    if (sepIndex === -1) return '';
+    return q.substring(sepIndex + separator.length);
+  });
+  protected readonly filteredItems = computed(() => {
+    const searchTerm = this.searchTerm().toLowerCase().trim();
+    const items = this.service.items();
+    const maxResults = this.service.config().maxResults ?? 10;
+    if (!searchTerm) {
+      // No query: sort by frecency scores from empty searches
+      const scores = this.frecency.getScores('');
+      return this.sortByFrecency(items, scores).slice(0, maxResults);
+    }
+    // Filter matching items using only search term (not args)
+    const matched = items.filter((item) => this.matchesQuery(item, searchTerm));
+    // Sort by frecency for this search term
+    const scores = this.frecency.getScores(searchTerm);
+    return this.sortByFrecency(matched, scores).slice(0, maxResults);
+  });
+  constructor(
+    protected readonly service: GigamenuService,
+    private readonly frecency: FrecencyService,
+    @Inject(PLATFORM_ID) platformId: object
+  ) {
+    this.isBrowser = isPlatformBrowser(platformId);
+    effect(() => {
+      if (this.service.isOpen() && this.isBrowser) {
+        setTimeout(() => this.searchInput()?.nativeElement.focus(), 0);
+      }
+    });
+    effect(() => {
+      const items = this.filteredItems();
+      const searchTerm = this.searchTerm();
+      // Check for auto-select based on frecency
+      if (searchTerm && items.length > 0) {
+        const topMatch = this.frecency.getTopMatch(searchTerm);
+        if (topMatch) {
+          const idx = items.findIndex((item) => item.id === topMatch);
+          if (idx !== -1) {
+            this.selectedIndex.set(idx);
+            return;
+          }
+        }
+      }
+      this.selectedIndex.set(0);
+    });
+  }
+  @HostListener('document:keydown', ['$event'])
+  onGlobalKeydown(event: KeyboardEvent): void {
+    if (!this.isBrowser) return;
+    if ((event.metaKey || event.ctrlKey) && event.key === 'k') {
+      event.preventDefault();
+      this.service.toggle();
+      return;
+    }
+    if (event.key === '/' && !this.isInputFocused()) {
+      event.preventDefault();
+      this.service.open();
+      return;
+    }
+    if (event.key === 'Escape' && this.service.isOpen()) {
+      event.preventDefault();
+      this.close();
+    }
+  }
+  protected onInputKeydown(event: KeyboardEvent): void {
+    const items = this.filteredItems();
+    switch (event.key) {
+      case 'ArrowDown':
+        event.preventDefault();
+        this.selectedIndex.update((i) => Math.min(i + 1, items.length - 1));
+        this.scrollSelectedIntoView();
+        break;
+      case 'ArrowUp':
+        event.preventDefault();
+        this.selectedIndex.update((i) => Math.max(i - 1, 0));
+        this.scrollSelectedIntoView();
+        break;
+      case 'Enter':
+        event.preventDefault();
+        const selected = items[this.selectedIndex()];
+        if (selected) {
+          this.executeItem(selected);
+        }
+        break;
+      case 'Escape':
+        event.preventDefault();
+        this.close();
+        break;
+    }
+  }
+  private scrollSelectedIntoView(): void {
+    const container = this.listContainer()?.nativeElement;
+    if (!container) return;
+    const selectedButton = container.querySelector(
+      `[data-index="${this.selectedIndex()}"]`
+    ) as HTMLElement | null;
+    if (selectedButton) {
+      selectedButton.scrollIntoView({ block: 'nearest' });
+    }
+  }
+  protected onQueryChange(event: Event): void {
+    const value = (event.target as HTMLInputElement).value;
+    this.query.set(value);
+  }
+  protected onBackdropClick(event: MouseEvent): void {
+    if (event.target === event.currentTarget) {
+      this.close();
+    }
+  }
+  protected executeItem(item: GigamenuItem): void {
+    // Record the selection for frecency learning (use search term, not full query)
+    const searchTerm = this.searchTerm();
+    this.frecency.recordSelection(searchTerm, item.id);
+    // Get args before closing (which resets query)
+    const args = this.args() || undefined;
+    this.close();
+    item.action(args);
+  }
+  // Template context getters
+  protected getItemContext(item: GigamenuItem, index: number): GigamenuItemContext {
+    return {
+      $implicit: item,
+      index,
+      selected: this.selectedIndex() === index,
+    };
+  }
+  protected getEmptyContext(): GigamenuEmptyContext {
+    return {
+      $implicit: this.query(),
+    };
+  }
+  protected getHeaderContext(): GigamenuHeaderContext {
+    return {
+      $implicit: this.query(),
+      searchTerm: this.searchTerm(),
+      args: this.args(),
+      onQueryChange: (value: string) => this.query.set(value),
+      onKeydown: (event: KeyboardEvent) => this.onInputKeydown(event),
+      placeholder: this.service.config().placeholder ?? '',
+    };
+  }
+  protected getFooterContext(): GigamenuFooterContext {
+    return {
+      $implicit: this.filteredItems().length,
+      total: this.service.items().length,
+    };
+  }
+  protected getPanelContext(): GigamenuPanelContext {
+    return {
+      $implicit: this.filteredItems(),
+      query: this.query(),
+      searchTerm: this.searchTerm(),
+      args: this.args(),
+      selectedIndex: this.selectedIndex(),
+      executeItem: (item: GigamenuItem) => this.executeItem(item),
+      setSelectedIndex: (index: number) => this.selectedIndex.set(index),
+      setQuery: (query: string) => this.query.set(query),
+      close: () => this.close(),
+      placeholder: this.service.config().placeholder ?? '',
+    };
+  }
+  private close(): void {
+    this.service.close();
+    this.query.set('');
+    this.selectedIndex.set(0);
+  }
+  private sortByFrecency(items: GigamenuItem[], scores: Map<string, number>): GigamenuItem[] {
+    if (scores.size === 0) return items;
+    return [...items].sort((a, b) => {
+      const scoreA = scores.get(a.id) ?? 0;
+      const scoreB = scores.get(b.id) ?? 0;
+      return scoreB - scoreA;
+    });
+  }
+  private matchesQuery(item: GigamenuItem, query: string): boolean {
+    const searchableText = [
+      item.label,
+      item.description,
+      ...(item.keywords ?? []),
+    ]
+      .filter(Boolean)
+      .join(' ')
+      .toLowerCase();
+    const words = query.split(/\s+/);
+    return words.every((word) => searchableText.includes(word));
+  }
+  private isInputFocused(): boolean {
+    const activeElement = document.activeElement;
+    if (!activeElement) return false;
+    const tagName = activeElement.tagName.toLowerCase();
+    return (
+      tagName === 'input' ||
+      tagName === 'textarea' ||
+      (activeElement as HTMLElement).isContentEditable
+    );
+  }
+}

package/src/lib/gigamenu.service.ts ADDED Viewed

@@ -0,0 +1,143 @@
+import { Injectable, signal, computed } from '@angular/core';
+import { Router, Route, Routes } from '@angular/router';
+import {
+  GigamenuItem,
+  GigamenuCommand,
+  GigamenuPage,
+  GigamenuConfig,
+  DEFAULT_CONFIG,
+  DiscoverRoutesOptions,
+  RouteInfo,
+} from './types';
+@Injectable({ providedIn: 'root' })
+export class GigamenuService {
+  private readonly _items = signal<Map<string, GigamenuItem>>(new Map());
+  private readonly _isOpen = signal(false);
+  private readonly _config = signal<GigamenuConfig>(DEFAULT_CONFIG);
+  readonly items = computed(() => Array.from(this._items().values()));
+  readonly isOpen = this._isOpen.asReadonly();
+  readonly config = this._config.asReadonly();
+  constructor(private readonly router: Router) {}
+  configure(config: Partial<GigamenuConfig>): void {
+    this._config.update((current) => ({ ...current, ...config }));
+  }
+  open(): void {
+    this._isOpen.set(true);
+  }
+  close(): void {
+    this._isOpen.set(false);
+  }
+  toggle(): void {
+    this._isOpen.update((v) => !v);
+  }
+  registerItem(item: GigamenuItem): void {
+    this._items.update((items) => {
+      const newItems = new Map(items);
+      newItems.set(item.id, item);
+      return newItems;
+    });
+  }
+  unregisterItem(id: string): void {
+    this._items.update((items) => {
+      const newItems = new Map(items);
+      newItems.delete(id);
+      return newItems;
+    });
+  }
+  registerCommand(command: GigamenuCommand): void {
+    this.registerItem({
+      ...command,
+      category: 'command',
+    });
+  }
+  registerPage(page: GigamenuPage): void {
+    this.registerItem({
+      ...page,
+      category: 'page',
+      action: () => this.router.navigate([page.path]),
+    });
+  }
+  discoverRoutes(options?: DiscoverRoutesOptions): void;
+  discoverRoutes(routes?: Routes, options?: DiscoverRoutesOptions): void;
+  discoverRoutes(
+    routesOrOptions?: Routes | DiscoverRoutesOptions,
+    maybeOptions?: DiscoverRoutesOptions
+  ): void {
+    let routes: Routes;
+    let options: DiscoverRoutesOptions | undefined;
+    if (Array.isArray(routesOrOptions)) {
+      routes = routesOrOptions;
+      options = maybeOptions;
+    } else {
+      routes = this.router.config;
+      options = routesOrOptions;
+    }
+    this.extractPagesFromRoutes(routes, '', options?.filter);
+  }
+  private extractPagesFromRoutes(
+    routes: Routes,
+    parentPath: string,
+    filter?: (route: RouteInfo) => boolean
+  ): void {
+    for (const route of routes) {
+      if (route.redirectTo !== undefined) continue;
+      const fullPath = parentPath
+        ? `${parentPath}/${route.path ?? ''}`
+        : route.path ?? '';
+      if (route.path !== undefined && route.path !== '**') {
+        const routeInfo: RouteInfo = {
+          path: route.path,
+          fullPath: `/${fullPath}`,
+          data: route.data as Record<string, unknown> | undefined,
+          title: typeof route.title === 'string' ? route.title : undefined,
+        };
+        // Apply filter if provided
+        if (filter && !filter(routeInfo)) {
+          // Still process children even if this route is filtered
+          if (route.children) {
+            this.extractPagesFromRoutes(route.children, fullPath, filter);
+          }
+          continue;
+        }
+        const label = routeInfo.title || this.pathToLabel(route.path || 'Home');
+        this.registerPage({
+          id: `page:${fullPath || '/'}`,
+          label,
+          path: `/${fullPath}`,
+          description: `Navigate to ${label}`,
+        });
+      }
+      if (route.children) {
+        this.extractPagesFromRoutes(route.children, fullPath, filter);
+      }
+    }
+  }
+  private pathToLabel(path: string): string {
+    return path
+      .split('/')
+      .pop()!
+      .replace(/[-_]/g, ' ')
+      .replace(/\b\w/g, (c) => c.toUpperCase());
+  }
+}

package/src/lib/types.ts ADDED Viewed

@@ -0,0 +1,101 @@
+export type GigamenuItemCategory = 'page' | 'command';
+export interface GigamenuItem {
+  id: string;
+  label: string;
+  description?: string;
+  /** Emoji or text icon */
+  icon?: string;
+  /** CSS class for icon libraries (e.g., 'pi pi-home', 'fa fa-home') */
+  iconClass?: string;
+  keywords?: string[];
+  category: GigamenuItemCategory;
+  /** Action to execute. Receives args string if user typed text after the separator. */
+  action: (args?: string) => void;
+}
+export interface GigamenuPage extends Omit<GigamenuItem, 'category' | 'action'> {
+  path: string;
+}
+export interface GigamenuCommand extends Omit<GigamenuItem, 'category'> {
+  shortcut?: string;
+}
+export interface GigamenuConfig {
+  placeholder?: string;
+  maxResults?: number;
+  autoDiscoverRoutes?: boolean;
+  /** Separator between search query and arguments (default: ' ') */
+  argSeparator?: string;
+}
+export const DEFAULT_CONFIG: GigamenuConfig = {
+  placeholder: 'Search pages and commands...',
+  maxResults: 10,
+  autoDiscoverRoutes: true,
+  argSeparator: ' ',
+};
+/**
+ * Base interface for defining a command in a separate file.
+ * Each command file should export a constant implementing this interface.
+ */
+export interface CommandDefinition {
+  readonly id: string;
+  readonly label: string;
+  readonly description?: string;
+  readonly icon?: string;
+  readonly iconClass?: string;
+  readonly keywords?: string[];
+  readonly shortcut?: string;
+  execute(): void;
+}
+/**
+ * Helper function to define a command with type safety.
+ */
+export function defineCommand(command: CommandDefinition): CommandDefinition {
+  return command;
+}
+/**
+ * Information about a route passed to the filter function.
+ */
+export interface RouteInfo {
+  path: string;
+  fullPath: string;
+  data?: Record<string, unknown>;
+  title?: string;
+}
+/**
+ * Filter function to include/exclude routes from discovery.
+ * Return true to include the route, false to exclude it.
+ */
+export type RouteFilter = (route: RouteInfo) => boolean;
+/**
+ * Mapped page data returned from the map function.
+ */
+export interface MappedPage {
+  label?: string;
+  description?: string;
+  icon?: string;
+  iconClass?: string;
+  keywords?: string[];
+}
+/**
+ * Map function to customize page data for discovered routes.
+ * Return partial page data to override defaults, or null to skip the route.
+ */
+export type RouteMapper = (route: RouteInfo) => MappedPage | null;
+/**
+ * Options for route discovery.
+ */
+export interface DiscoverRoutesOptions {
+  filter?: RouteFilter;
+  map?: RouteMapper;
+}

package/src/public-api.ts ADDED Viewed

@@ -0,0 +1,6 @@
+export * from './lib/types';
+export { defineCommand } from './lib/types';
+export * from './lib/gigamenu.service';
+export * from './lib/gigamenu.component';
+export * from './lib/frecency.service';
+export * from './lib/gigamenu-templates.directive';

package/tsconfig.json ADDED Viewed

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "experimentalDecorators": true,
+    "useDefineForClassFields": false
+  }
+}

package/tsconfig.lib.json ADDED Viewed

@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "out-tsc/lib",
+    "declaration": true,
+    "declarationMap": true,
+    "inlineSources": true,
+    "baseUrl": "."
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["**/*.spec.ts"]
+}

package/tsconfig.lib.prod.json ADDED Viewed

@@ -0,0 +1,6 @@
+{
+  "extends": "./tsconfig.lib.json",
+  "compilerOptions": {
+    "declarationMap": false
+  }
+}