@checkstack/command-frontend 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,56 @@
+# @checkstack/command-frontend
+
+## 0.0.2
+
+### Patch Changes
+
+- d20d274: Initial release of all @checkstack packages. Rebranded from Checkmate to Checkstack with new npm organization @checkstack and domain checkstack.dev.
+- Updated dependencies [d20d274]
+  - @checkstack/command-common@0.0.2
+  - @checkstack/common@0.0.2
+  - @checkstack/frontend-api@0.0.2
+  - @checkstack/ui@0.0.2
+
+## 0.1.0
+
+### Minor Changes
+
+- ae33df2: Move command palette from dashboard to centered navbar position
+
+  - Converted `command-frontend` into a plugin with `NavbarCenterSlot` extension
+  - Added compact `NavbarSearch` component with responsive search trigger
+  - Moved `SearchDialog` from dashboard-frontend to command-frontend
+  - Keyboard shortcut (⌘K / Ctrl+K) now works on every page
+  - Renamed navbar slots for clarity:
+    - `NavbarSlot` → `NavbarRightSlot`
+    - `NavbarMainSlot` → `NavbarLeftSlot`
+    - Added new `NavbarCenterSlot` for centered content
+
+### Patch Changes
+
+- Updated dependencies [52231ef]
+- Updated dependencies [b0124ef]
+- Updated dependencies [54cc787]
+- Updated dependencies [a65e002]
+- Updated dependencies [ae33df2]
+- Updated dependencies [32ea706]
+  - @checkstack/ui@0.1.2
+  - @checkstack/common@0.2.0
+  - @checkstack/frontend-api@0.1.0
+  - @checkstack/command-common@0.0.3
+
+## 0.0.3
+
+### Patch Changes
+
+- Updated dependencies [0f8cc7d]
+  - @checkstack/frontend-api@0.0.3
+
+## 0.0.2
+
+### Patch Changes
+
+- Updated dependencies [ffc28f6]
+  - @checkstack/common@0.1.0
+  - @checkstack/command-common@0.0.2
+  - @checkstack/frontend-api@0.0.2

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@checkstack/command-frontend",
+  "version": "0.0.2",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/index.tsx"
+    }
+  },
+  "dependencies": {
+    "@checkstack/command-common": "workspace:*",
+    "@checkstack/common": "workspace:*",
+    "@checkstack/frontend-api": "workspace:*",
+    "@checkstack/ui": "workspace:*",
+    "lucide-react": "^0.468.0",
+    "react": "^18.2.0",
+    "react-router-dom": "^7.1.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "@types/react": "^18.2.0",
+    "@checkstack/tsconfig": "workspace:*",
+    "@checkstack/scripts": "workspace:*"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  }
+}

package/src/components/NavbarSearch.tsx

@@ -0,0 +1,89 @@
+import { useState, useEffect, useMemo } from "react";
+import { cn } from "@checkstack/ui";
+import { Search, Command } from "lucide-react";
+import { SearchDialog } from "./SearchDialog";
+
+/**
+ * NavbarSearch - Compact command palette trigger for the navbar.
+ * Displays a small search button that opens the global search dialog.
+ * Includes the ⌘K keyboard shortcut listener.
+ */
+export const NavbarSearch = () => {
+  const [searchOpen, setSearchOpen] = useState(false);
+
+  // Detect Mac for keyboard shortcut display
+  const isMac = useMemo(
+    () =>
+      typeof navigator !== "undefined" &&
+      /Mac|iPhone|iPad/.test(navigator.userAgent),
+    []
+  );
+
+  // Global keyboard shortcut for search (⌘K / Ctrl+K)
+  useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if ((e.metaKey || e.ctrlKey) && e.key === "k") {
+        e.preventDefault();
+        setSearchOpen(true);
+      }
+    };
+
+    document.addEventListener("keydown", handleKeyDown);
+    return () => document.removeEventListener("keydown", handleKeyDown);
+  }, []);
+
+  return (
+    <>
+      {/* Search Dialog */}
+      <SearchDialog open={searchOpen} onOpenChange={setSearchOpen} />
+
+      {/* Compact trigger button */}
+      <button
+        onClick={() => setSearchOpen(true)}
+        className={cn(
+          // Base styles
+          "flex items-center gap-2 px-3 py-1.5 rounded-lg",
+          // Glassmorphism effect
+          "bg-muted/50 border border-primary/30",
+          // Subtle primary pulse animation
+          "animate-pulse-subtle ring-1 ring-primary/20",
+          // Hover state
+          "hover:bg-muted hover:border-primary/50 hover:ring-primary/40",
+          // Transition
+          "transition-all duration-200",
+          // Focus ring
+          "focus:outline-none focus:ring-2 focus:ring-primary/50 focus:ring-offset-2 focus:ring-offset-background",
+          // Cursor
+          "cursor-pointer"
+        )}
+        style={{
+          animation: "pulse-glow 3s ease-in-out infinite",
+        }}
+        aria-label="Open search"
+      >
+        <Search className="w-4 h-4 text-muted-foreground" />
+        {/* Show placeholder text only on larger screens */}
+        <span className="hidden md:inline text-sm text-muted-foreground">
+          Search...
+        </span>
+        {/* Keyboard shortcut badge - hidden on small screens */}
+        <kbd
+          className={cn(
+            "hidden sm:flex items-center gap-0.5 px-1.5 py-0.5 rounded",
+            "bg-background/50 border border-border/50",
+            "text-xs text-muted-foreground font-mono"
+          )}
+        >
+          {isMac ? (
+            <>
+              <Command className="w-3 h-3" />
+              <span>K</span>
+            </>
+          ) : (
+            <span>Ctrl+K</span>
+          )}
+        </kbd>
+      </button>
+    </>
+  );
+};

package/src/components/SearchDialog.tsx

@@ -0,0 +1,231 @@
+import React, { useState, useEffect, useCallback, useRef } from "react";
+import { useNavigate } from "react-router-dom";
+import {
+  Dialog,
+  DialogContent,
+  Input,
+  DynamicIcon,
+  type LucideIconName,
+} from "@checkstack/ui";
+import { useDebouncedSearch, useFormatShortcut } from "../index";
+import type { SearchResult } from "@checkstack/command-common";
+import { Search, ArrowUp, ArrowDown, CornerDownLeft } from "lucide-react";
+
+interface SearchDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}
+
+export const SearchDialog: React.FC<SearchDialogProps> = ({
+  open,
+  onOpenChange,
+}) => {
+  const navigate = useNavigate();
+  const formatShortcut = useFormatShortcut();
+  const { results, loading, search, reset } = useDebouncedSearch(300);
+
+  const [query, setQuery] = useState("");
+  const [selectedIndex, setSelectedIndex] = useState(0);
+
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  // Trigger search when dialog opens or query changes
+  useEffect(() => {
+    if (open) {
+      search(query);
+      // Focus input after dialog opens
+      setTimeout(() => inputRef.current?.focus(), 50);
+    } else {
+      // Reset state when dialog closes
+      setQuery("");
+      setSelectedIndex(0);
+      reset();
+    }
+  }, [open, query, search, reset]);
+
+  // Group results by category
+  const groupedResults: Record<string, SearchResult[]> = {};
+  for (const result of results) {
+    const category = result.category;
+    if (!groupedResults[category]) {
+      groupedResults[category] = [];
+    }
+    groupedResults[category].push(result);
+  }
+
+  // Flatten for navigation
+  const flatResults = Object.values(groupedResults).flat();
+
+  // Reset selection when results change
+  useEffect(() => {
+    setSelectedIndex(0);
+  }, [results]);
+
+  const handleSelect = useCallback(
+    (result: SearchResult) => {
+      onOpenChange(false);
+      if (result.route) {
+        navigate(result.route);
+      }
+    },
+    [navigate, onOpenChange]
+  );
+
+  // Keyboard navigation
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      switch (e.key) {
+        case "ArrowDown": {
+          e.preventDefault();
+          setSelectedIndex((prev) =>
+            Math.min(prev + 1, flatResults.length - 1)
+          );
+          break;
+        }
+        case "ArrowUp": {
+          e.preventDefault();
+          setSelectedIndex((prev) => Math.max(prev - 1, 0));
+          break;
+        }
+        case "Enter": {
+          e.preventDefault();
+          if (flatResults[selectedIndex]) {
+            handleSelect(flatResults[selectedIndex]);
+          }
+          break;
+        }
+        case "Escape": {
+          e.preventDefault();
+          onOpenChange(false);
+          break;
+        }
+      }
+    },
+    [flatResults, selectedIndex, handleSelect, onOpenChange]
+  );
+
+  // Render a single result item
+  const renderResult = (result: SearchResult, globalIndex: number) => {
+    const isSelected = globalIndex === selectedIndex;
+
+    return (
+      <button
+        key={result.id}
+        onClick={() => handleSelect(result)}
+        onMouseEnter={() => setSelectedIndex(globalIndex)}
+        className={`w-full flex items-center gap-3 px-4 py-2 text-left transition-colors ${
+          isSelected
+            ? "bg-primary/10 text-foreground"
+            : "text-muted-foreground hover:bg-muted/50"
+        }`}
+      >
+        <DynamicIcon
+          name={result.iconName as LucideIconName}
+          className="w-4 h-4 flex-shrink-0"
+        />
+        <div className="flex-1 min-w-0">
+          <span className="block truncate">{result.title}</span>
+          {result.subtitle && (
+            <span className="block text-xs text-muted-foreground truncate">
+              {result.subtitle}
+            </span>
+          )}
+        </div>
+        {/* Show shortcuts for commands */}
+        {result.type === "command" &&
+          result.shortcuts &&
+          result.shortcuts.length > 0 && (
+            <div className="flex gap-1">
+              {result.shortcuts.slice(0, 1).map((shortcut) => (
+                <kbd
+                  key={shortcut}
+                  className="px-1.5 py-0.5 text-xs rounded bg-muted border border-border font-mono"
+                >
+                  {formatShortcut(shortcut)}
+                </kbd>
+              ))}
+            </div>
+          )}
+        {isSelected && (
+          <CornerDownLeft className="w-4 h-4 text-muted-foreground flex-shrink-0" />
+        )}
+      </button>
+    );
+  };
+
+  // Track global index for selection
+  let globalIndex = 0;
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent
+        size="lg"
+        className="p-0 gap-0 overflow-hidden"
+        onKeyDown={handleKeyDown}
+      >
+        {/* Search input */}
+        <div className="flex items-center gap-3 px-4 py-3 border-b border-border">
+          <Search className="w-5 h-5 text-muted-foreground flex-shrink-0" />
+          <Input
+            ref={inputRef}
+            value={query}
+            onChange={(e: React.ChangeEvent<HTMLInputElement>) =>
+              setQuery(e.target.value)
+            }
+            placeholder="Search commands and systems..."
+            className="border-0 bg-transparent focus-visible:ring-0 px-0 text-base"
+          />
+        </div>
+
+        {/* Results */}
+        <div className="max-h-[300px] overflow-y-auto py-2">
+          {loading ? (
+            <div className="px-4 py-8 text-center text-muted-foreground">
+              Searching...
+            </div>
+          ) : flatResults.length === 0 ? (
+            <div className="px-4 py-8 text-center text-muted-foreground">
+              {query ? "No results found" : "Start typing to search..."}
+            </div>
+          ) : (
+            Object.entries(groupedResults).map(
+              ([category, categoryResults]) => (
+                <div key={category}>
+                  {/* Category header */}
+                  <div className="px-4 py-1.5 text-xs font-medium text-muted-foreground uppercase tracking-wider bg-muted/30">
+                    {category} ({categoryResults.length})
+                  </div>
+                  {/* Category results */}
+                  {categoryResults.map((result) => {
+                    const element = renderResult(result, globalIndex);
+                    globalIndex++;
+                    return element;
+                  })}
+                </div>
+              )
+            )
+          )}
+        </div>
+
+        {/* Footer with keyboard hints */}
+        <div className="flex items-center gap-4 px-4 py-2 border-t border-border bg-muted/30 text-xs text-muted-foreground">
+          <div className="flex items-center gap-1">
+            <ArrowUp className="w-3 h-3" />
+            <ArrowDown className="w-3 h-3" />
+            <span>Navigate</span>
+          </div>
+          <div className="flex items-center gap-1">
+            <CornerDownLeft className="w-3 h-3" />
+            <span>Select</span>
+          </div>
+          <div className="flex items-center gap-1">
+            <kbd className="px-1 rounded bg-muted border border-border font-mono">
+              esc
+            </kbd>
+            <span>Close</span>
+          </div>
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+};

package/src/index.tsx

@@ -0,0 +1,368 @@
+import { useEffect, useCallback, useMemo, useState, useRef } from "react";
+import {
+  useApi,
+  rpcApiRef,
+  createApiRef,
+  createFrontendPlugin,
+  NavbarCenterSlot,
+} from "@checkstack/frontend-api";
+import {
+  CommandApi,
+  pluginMetadata,
+  type SearchResult,
+} from "@checkstack/command-common";
+import type { InferClient } from "@checkstack/common";
+import { NavbarSearch } from "./components/NavbarSearch";
+
+// =============================================================================
+// PLUGIN
+// =============================================================================
+
+export const commandPlugin = createFrontendPlugin({
+  metadata: pluginMetadata,
+  routes: [],
+  extensions: [
+    {
+      id: "command.navbar.search",
+      slot: NavbarCenterSlot,
+      component: NavbarSearch,
+    },
+  ],
+});
+
+// =============================================================================
+// API REF
+// =============================================================================
+
+export type CommandApiClient = InferClient<typeof CommandApi>;
+
+export const commandApiRef =
+  createApiRef<CommandApiClient>("plugin.command.api");
+
+// =============================================================================
+// SHORTCUT UTILITIES (Frontend-only - requires DOM types)
+// =============================================================================
+
+interface ParsedShortcut {
+  meta: boolean;
+  ctrl: boolean;
+  alt: boolean;
+  shift: boolean;
+  key: string;
+}
+
+/**
+ * Parse a shortcut string like "meta+shift+k" into components.
+ */
+function parseShortcut(shortcut: string): ParsedShortcut {
+  const parts = shortcut.toLowerCase().split("+");
+  const key = parts.pop() ?? "";
+  return {
+    meta: parts.includes("meta"),
+    ctrl: parts.includes("ctrl"),
+    alt: parts.includes("alt"),
+    shift: parts.includes("shift"),
+    key,
+  };
+}
+
+/**
+ * Check if a keyboard event matches a parsed shortcut.
+ */
+function matchesShortcut(
+  event: KeyboardEvent,
+  shortcut: ParsedShortcut
+): boolean {
+  return (
+    event.metaKey === shortcut.meta &&
+    event.ctrlKey === shortcut.ctrl &&
+    event.altKey === shortcut.alt &&
+    event.shiftKey === shortcut.shift &&
+    event.key.toLowerCase() === shortcut.key
+  );
+}
+
+/**
+ * Format a shortcut for display.
+ * "meta+i" → "⌘I" on Mac, "Ctrl+I" on Windows
+ */
+export function formatShortcut(shortcut: string, isMac: boolean): string {
+  const parsed = parseShortcut(shortcut);
+  const parts: string[] = [];
+
+  if (parsed.ctrl) {
+    parts.push(isMac ? "⌃" : "Ctrl");
+  }
+  if (parsed.alt) {
+    parts.push(isMac ? "⌥" : "Alt");
+  }
+  if (parsed.shift) {
+    parts.push(isMac ? "⇧" : "Shift");
+  }
+  if (parsed.meta) {
+    parts.push(isMac ? "⌘" : "Win");
+  }
+  parts.push(parsed.key.toUpperCase());
+
+  return isMac ? parts.join("") : parts.join("+");
+}
+
+// =============================================================================
+// HOOKS
+// =============================================================================
+
+/**
+ * Hook that registers global keyboard shortcuts for commands.
+ * When a shortcut is triggered, it navigates to the command's route.
+ * Should be used once at the app root level.
+ *
+ * @param commands - Array of commands with shortcuts
+ * @param navigate - Navigation function to call when a command is triggered
+ * @param userPermissions - Array of permission IDs the user has
+ */
+export function useGlobalShortcuts(
+  commands: SearchResult[],
+  navigate: (route: string) => void,
+  userPermissions: string[]
+): void {
+  useEffect(() => {
+    // Check if user has wildcard permission (admin)
+    const hasWildcard = userPermissions.includes("*");
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      // Don't trigger in input fields
+      const target = event.target as HTMLElement;
+      if (
+        target.tagName === "INPUT" ||
+        target.tagName === "TEXTAREA" ||
+        target.isContentEditable
+      ) {
+        return;
+      }
+
+      // Find matching command
+      for (const command of commands) {
+        if (!command.shortcuts || !command.route) continue;
+
+        // Check permissions (skip if user has wildcard)
+        if (!hasWildcard && command.requiredPermissions?.length) {
+          const hasPermission = command.requiredPermissions.every((perm) =>
+            userPermissions.includes(perm)
+          );
+          if (!hasPermission) continue;
+        }
+
+        for (const shortcut of command.shortcuts) {
+          const parsed = parseShortcut(shortcut);
+          if (matchesShortcut(event, parsed)) {
+            event.preventDefault();
+            navigate(command.route);
+            return;
+          }
+        }
+      }
+    };
+
+    globalThis.addEventListener("keydown", handleKeyDown);
+    return () => globalThis.removeEventListener("keydown", handleKeyDown);
+  }, [commands, navigate, userPermissions]);
+}
+
+/**
+ * Hook to format a shortcut string for the current platform.
+ */
+export function useFormatShortcut(): (shortcut: string) => string {
+  const isMac = useMemo(
+    () =>
+      typeof navigator !== "undefined" &&
+      /Mac|iPhone|iPad/.test(navigator.userAgent),
+    []
+  );
+
+  return useCallback(
+    (shortcut: string) => formatShortcut(shortcut, isMac),
+    [isMac]
+  );
+}
+
+/**
+ * Hook to search across all providers via backend RPC.
+ * Returns search function and loading state.
+ */
+export function useCommandPaletteSearch(): {
+  search: (query: string) => Promise<SearchResult[]>;
+  getCommands: () => Promise<SearchResult[]>;
+  loading: boolean;
+} {
+  const rpcApi = useApi(rpcApiRef);
+  const commandApi = useMemo(() => rpcApi.forPlugin(CommandApi), [rpcApi]);
+  const [loading, setLoading] = useState(false);
+
+  const search = useCallback(
+    async (query: string): Promise<SearchResult[]> => {
+      setLoading(true);
+      try {
+        return await commandApi.search({ query });
+      } finally {
+        setLoading(false);
+      }
+    },
+    [commandApi]
+  );
+
+  const getCommands = useCallback(async (): Promise<SearchResult[]> => {
+    setLoading(true);
+    try {
+      return await commandApi.getCommands();
+    } finally {
+      setLoading(false);
+    }
+  }, [commandApi]);
+
+  return { search, getCommands, loading };
+}
+
+/**
+ * Hook for debounced search in the command palette.
+ * Automatically debounces the search query by the specified delay.
+ */
+export function useDebouncedSearch(delayMs: number = 300): {
+  results: SearchResult[];
+  loading: boolean;
+  search: (query: string) => void;
+  reset: () => void;
+} {
+  const { search: doSearch, getCommands } = useCommandPaletteSearch();
+  const [results, setResults] = useState<SearchResult[]>([]);
+  const [loading, setLoading] = useState(false);
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const search = useCallback(
+    (query: string) => {
+      // Clear any pending search
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+      }
+
+      // If empty query, fetch all results immediately (commands + entities)
+      if (!query.trim()) {
+        setLoading(true);
+        doSearch("")
+          .then(setResults)
+          .catch(() => setResults([]))
+          .finally(() => setLoading(false));
+        return;
+      }
+
+      // Debounce non-empty queries
+      setLoading(true);
+      timeoutRef.current = setTimeout(() => {
+        doSearch(query)
+          .then(setResults)
+          .catch(() => setResults([]))
+          .finally(() => setLoading(false));
+      }, delayMs);
+    },
+    [doSearch, getCommands, delayMs]
+  );
+
+  const reset = useCallback(() => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+    }
+    setResults([]);
+    setLoading(false);
+  }, []);
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+      }
+    };
+  }, []);
+
+  return { results, loading, search, reset };
+}
+
+// =============================================================================
+// GLOBAL SHORTCUTS COMPONENT
+// =============================================================================
+
+/**
+ * Hook to fetch commands with shortcuts from the backend.
+ * Returns commands that can be used with useGlobalShortcuts.
+ */
+export function useCommands(): {
+  commands: SearchResult[];
+  loading: boolean;
+} {
+  const rpcApi = useApi(rpcApiRef);
+  const commandApi = useMemo(() => rpcApi.forPlugin(CommandApi), [rpcApi]);
+  const [commands, setCommands] = useState<SearchResult[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function fetchCommands() {
+      try {
+        const results = await commandApi.getCommands();
+        if (!cancelled) {
+          // Filter to only commands with shortcuts
+          setCommands(
+            results.filter((r) => r.shortcuts && r.shortcuts.length > 0)
+          );
+        }
+      } catch {
+        // Ignore errors - commands just won't be available
+      } finally {
+        if (!cancelled) {
+          setLoading(false);
+        }
+      }
+    }
+
+    fetchCommands();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [commandApi]);
+
+  return { commands, loading };
+}
+
+/**
+ * Component that registers global keyboard shortcuts for commands.
+ * Mount this at the app root level (e.g., in Layout or App).
+ *
+ * @example
+ * ```tsx
+ * import { GlobalShortcuts } from "@checkstack/command-frontend";
+ *
+ * function App() {
+ *   return (
+ *     <>
+ *       <GlobalShortcuts />
+ *       {/* rest of app *\/}
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function GlobalShortcuts(): React.ReactNode {
+  const { commands } = useCommands();
+  const navigate = useCallback((route: string) => {
+    // Use window.location for reliable navigation
+    globalThis.location.href = route;
+  }, []);
+
+  // For now, pass "*" as permission since the backend already filters by permission
+  // The commands returned from getCommands are already filtered
+  useGlobalShortcuts(commands, navigate, ["*"]);
+
+  // This component renders nothing - it only registers event listeners
+  return;
+}

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkstack/tsconfig/frontend.json",
+  "include": [
+    "src"
+  ]
+}