Merge branch 'main' into fix/ui-tweaks

Author: NandkishorJadoun

CONTRIBUTING.md

@@ -33,6 +33,7 @@ This focus helps guide our project decisions as a community and what we choose t
   - [Available commands](#available-commands)
   - [Project structure](#project-structure)
   - [Local connector CLI](#local-connector-cli)
+  - [Mock connector (for local development)](#mock-connector-for-local-development)
 - [Code style](#code-style)
   - [TypeScript](#typescript)
   - [Server API patterns](#server-api-patterns)
@@ -104,6 +105,10 @@ pnpm dev              # Start development server
 pnpm build            # Production build
 pnpm preview          # Preview production build
 
+# Connector
+pnpm npmx-connector   # Start the real connector (requires npm login)
+pnpm mock-connector   # Start the mock connector (no npm login needed)
+
 # Code Quality
 pnpm lint             # Run linter (oxlint + oxfmt)
 pnpm lint:fix         # Auto-fix lint issues
@@ -157,6 +162,36 @@ pnpm npmx-connector
 
 The connector will check your npm authentication, generate a connection token, and listen for requests from npmx.dev.
 
+### Mock connector (for local development)
+
+If you're working on admin features (org management, package access controls, operations queue) and don't want to use your real npm account, you can run the mock connector instead:
+
+```bash
+pnpm mock-connector
+```
+
+This starts a mock connector server pre-populated with sample data (orgs, teams, members, packages). No npm login is required — operations succeed immediately without making real npm CLI calls.
+
+The mock connector prints a connection URL to the terminal, just like the real connector. Click it (or paste the token manually) to connect the UI.
+
+**Options:**
+
+```bash
+pnpm mock-connector                # default: port 31415, user "mock-user", sample data
+pnpm mock-connector --port 9999    # custom port
+pnpm mock-connector --user alice   # custom username
+pnpm mock-connector --empty        # start with no pre-populated data
+```
+
+**Default sample data:**
+
+- **@nuxt**: 4 members (mock-user, danielroe, pi0, antfu), 3 teams (core, docs, triage)
+- **@unjs**: 2 members (mock-user, pi0), 1 team (maintainers)
+- **Packages**: @nuxt/kit, @nuxt/schema, @unjs/nitro with team-based access controls
+
+> [!TIP]
+> Run `pnpm dev` in a separate terminal to start the Nuxt dev server, then click the connection URL from the mock connector to connect.
+
 ## Code style
 
 When committing changes, try to keep an eye out for unintended formatting updates. These can make a pull request look noisier than it really is and slow down the review process. Sometimes IDEs automatically reformat files on save, which can unintentionally introduce extra changes.
@@ -752,6 +787,74 @@ You need to either:
 1. Add a fixture file for that package/endpoint
 2. Update the mock handlers in `test/fixtures/mock-routes.cjs` (client) or `modules/runtime/server/cache.ts` (server)
 
+### Testing connector features
+
+Features that require authentication through the local connector (org management, package collaborators, operations queue) are tested using a mock connector server.
+
+#### Architecture
+
+The mock connector infrastructure is shared between the CLI, E2E tests, and Vitest component tests:
+
+```
+cli/src/
+├── types.ts           # ConnectorEndpoints contract (shared by real + mock)
+├── mock-state.ts      # MockConnectorStateManager (canonical source)
+├── mock-app.ts        # H3 mock app + MockConnectorServer class
+└── mock-server.ts     # CLI entry point (pnpm mock-connector)
+
+test/test-utils/       # Re-exports from cli/src/ for test convenience
+test/e2e/helpers/      # E2E-specific wrappers (fixtures, global setup)
+```
+
+Both the real server (`cli/src/server.ts`) and the mock server (`cli/src/mock-app.ts`) conform to the `ConnectorEndpoints` interface defined in `cli/src/types.ts`. This ensures the API contract is enforced by TypeScript. When adding a new endpoint, update `ConnectorEndpoints` first, then implement it in both servers.
+
+#### Vitest component tests (`test/nuxt/`)
+
+- Mock the `useConnector` composable with reactive state
+- Use `document.body` queries for components using Teleport
+- See `test/nuxt/components/HeaderConnectorModal.spec.ts` for an example
+
+```typescript
+// Create mock state
+const mockState = ref({ connected: false, npmUser: null, ... })
+
+// Mock the composable
+vi.mock('~/composables/useConnector', () => ({
+  useConnector: () => ({
+    isConnected: computed(() => mockState.value.connected),
+    // ... other properties
+  }),
+}))
+```
+
+#### Playwright E2E tests (`test/e2e/`)
+
+- A mock HTTP server starts automatically via Playwright's global setup
+- Use the `mockConnector` fixture to set up test data and the `gotoConnected` helper to navigate with authentication
+
+```typescript
+test('shows org members', async ({ page, gotoConnected, mockConnector }) => {
+  // Set up test data
+  await mockConnector.setOrgData('@testorg', {
+    users: { testuser: 'owner', member1: 'admin' },
+  })
+
+  // Navigate with connector authentication
+  await gotoConnected('/@testorg')
+
+  // Test assertions
+  await expect(page.getByRole('link', { name: '@testuser' })).toBeVisible()
+})
+```
+
+The mock connector supports test endpoints for state manipulation:
+
+- `/__test__/reset` - Reset all mock state
+- `/__test__/org` - Set org users, teams, and team members
+- `/__test__/user-orgs` - Set user's organizations
+- `/__test__/user-packages` - Set user's packages
+- `/__test__/package` - Set package collaborators
+
 ## Submitting changes
 
 ### Before submitting

app/app.vue

@@ -127,7 +127,7 @@ if (import.meta.client) {
 
     <AppHeader :show-logo="!isHomepage" />
 
-    <div id="main-content" class="flex-1 flex flex-col">
+    <div id="main-content" class="flex-1 flex flex-col" tabindex="-1">
       <NuxtPage />
     </div>
 

app/components/CollapsibleSection.vue

@@ -26,7 +26,7 @@ onPrehydrate(() => {
   const settings = JSON.parse(localStorage.getItem('npmx-settings') || '{}')
   const collapsed: string[] = settings?.sidebar?.collapsed || []
   for (const id of collapsed) {
-    if (!document.documentElement.dataset.collapsed?.includes(id)) {
+    if (!document.documentElement.dataset.collapsed?.split(' ').includes(id)) {
       document.documentElement.dataset.collapsed = (
         document.documentElement.dataset.collapsed +
         ' ' +
@@ -38,7 +38,9 @@ onPrehydrate(() => {
 
 onMounted(() => {
   if (document?.documentElement) {
-    isOpen.value = !(document.documentElement.dataset.collapsed?.includes(props.id) ?? false)
+    isOpen.value = !(
+      document.documentElement.dataset.collapsed?.split(' ').includes(props.id) ?? false
+    )
   }
 })
 

app/components/Compare/PackageSelector.vue

@@ -14,8 +14,14 @@ const maxPackages = computed(() => props.max ?? 4)
 const inputValue = shallowRef('')
 const isInputFocused = shallowRef(false)
 
+// Keyboard navigation state
+const highlightedIndex = shallowRef(-1)
+const listRef = useTemplateRef('listRef')
+const PAGE_JUMP = 5
+
 // Use the shared search composable (supports both npm and Algolia providers)
-const { data: searchData, status } = useSearch(inputValue, { size: 15 })
+const { searchProvider } = useSearchProvider()
+const { data: searchData, status } = useSearch(inputValue, searchProvider, { size: 15 })
 
 const isSearching = computed(() => status.value === 'pending')
 
@@ -53,6 +59,20 @@ const filteredResults = computed(() => {
     .filter(r => !packages.value.includes(r.name))
 })
 
+// Unified list of navigable items for keyboard navigation
+const navigableItems = computed(() => {
+  const items: { type: 'no-dependency' | 'package'; name: string }[] = []
+  if (showNoDependencyOption.value) {
+    items.push({ type: 'no-dependency', name: NO_DEPENDENCY_ID })
+  }
+  for (const r of filteredResults.value) {
+    items.push({ type: 'package', name: r.name })
+  }
+  return items
+})
+
+const resultIndexOffset = computed(() => (showNoDependencyOption.value ? 1 : 0))
+
 const numberFormatter = useNumberFormatter()
 
 function addPackage(name: string) {
@@ -70,30 +90,93 @@ function addPackage(name: string) {
     packages.value = [...packages.value, name]
   }
   inputValue.value = ''
+  highlightedIndex.value = -1
 }
 
 function removePackage(name: string) {
   packages.value = packages.value.filter(p => p !== name)
 }
 
 function handleKeydown(e: KeyboardEvent) {
-  const inputValueTrim = inputValue.value.trim()
-  const hasMatchInPackages = filteredResults.value.find(result => {
-    return result.name === inputValueTrim
-  })
-
-  if (e.key === 'Enter' && inputValueTrim) {
-    e.preventDefault()
-    if (showNoDependencyOption.value) {
-      addPackage(NO_DEPENDENCY_ID)
-    } else if (hasMatchInPackages) {
-      addPackage(inputValueTrim)
+  const items = navigableItems.value
+  const count = items.length
+
+  switch (e.key) {
+    case 'ArrowDown':
+      e.preventDefault()
+      if (count === 0) return
+      highlightedIndex.value = Math.min(highlightedIndex.value + 1, count - 1)
+      break
+
+    case 'ArrowUp':
+      e.preventDefault()
+      if (count === 0) return
+      if (highlightedIndex.value > 0) {
+        highlightedIndex.value--
+      }
+      break
+
+    case 'PageDown':
+      e.preventDefault()
+      if (count === 0) return
+      if (highlightedIndex.value === -1) {
+        highlightedIndex.value = Math.min(PAGE_JUMP - 1, count - 1)
+      } else {
+        highlightedIndex.value = Math.min(highlightedIndex.value + PAGE_JUMP, count - 1)
+      }
+      break
+
+    case 'PageUp':
+      e.preventDefault()
+      if (count === 0) return
+      highlightedIndex.value = Math.max(highlightedIndex.value - PAGE_JUMP, 0)
+      break
+
+    case 'Enter': {
+      const inputValueTrim = inputValue.value.trim()
+      if (!inputValueTrim) return
+
+      e.preventDefault()
+
+      // If an item is highlighted, select it
+      if (highlightedIndex.value >= 0 && highlightedIndex.value < count) {
+        addPackage(items[highlightedIndex.value]!.name)
+        return
+      }
+
+      // Fallback: exact match or easter egg (preserves existing behavior)
+      if (showNoDependencyOption.value) {
+        addPackage(NO_DEPENDENCY_ID)
+      } else {
+        const hasMatch = filteredResults.value.find(r => r.name === inputValueTrim)
+        if (hasMatch) {
+          addPackage(inputValueTrim)
+        }
+      }
+      break
     }
-  } else if (e.key === 'Escape') {
-    inputValue.value = ''
+
+    case 'Escape':
+      inputValue.value = ''
+      highlightedIndex.value = -1
+      break
   }
 }
 
+// Reset highlight when user types
+watch(inputValue, () => {
+  highlightedIndex.value = -1
+})
+
+// Scroll highlighted item into view
+watch(highlightedIndex, index => {
+  if (index >= 0 && listRef.value) {
+    const items = listRef.value.querySelectorAll('[data-navigable]')
+    const item = items[index] as HTMLElement | undefined
+    item?.scrollIntoView({ block: 'nearest' })
+  }
+})
+
 const { start, stop } = useTimeoutFn(() => {
   isInputFocused.value = false
 }, 200)
@@ -175,16 +258,18 @@ function handleFocus() {
         leave-to-class="opacity-0"
       >
         <div
-          v-if="
-            isInputFocused && (filteredResults.length > 0 || isSearching || showNoDependencyOption)
-          "
+          v-if="isInputFocused && (navigableItems.length > 0 || isSearching)"
+          ref="listRef"
           class="absolute top-full inset-x-0 mt-1 bg-bg-elevated border border-border rounded-lg shadow-lg z-50 max-h-64 overflow-y-auto"
         >
           <!-- No dependency option (easter egg with James) -->
           <ButtonBase
             v-if="showNoDependencyOption"
+            data-navigable
             class="block w-full text-start"
+            :class="highlightedIndex === 0 ? '!bg-accent/15' : ''"
             :aria-label="$t('compare.no_dependency.add_column')"
+            @mouseenter="highlightedIndex = 0"
             @click="addPackage(NO_DEPENDENCY_ID)"
           >
             <span class="text-sm text-accent italic flex items-center gap-2">
@@ -196,13 +281,19 @@ function handleFocus() {
             </span>
           </ButtonBase>
 
-          <div v-if="isSearching" class="px-4 py-3 text-sm text-fg-muted">
+          <div
+            v-if="isSearching && navigableItems.length === 0"
+            class="px-4 py-3 text-sm text-fg-muted"
+          >
             {{ $t('compare.selector.searching') }}
           </div>
           <ButtonBase
-            v-for="result in filteredResults"
+            v-for="(result, index) in filteredResults"
             :key="result.name"
+            data-navigable
             class="block w-full text-start"
+            :class="highlightedIndex === index + resultIndexOffset ? '!bg-accent/15' : ''"
+            @mouseenter="highlightedIndex = index + resultIndexOffset"
             @click="addPackage(result.name)"
           >
             <span class="font-mono text-sm text-fg block">{{ result.name }}</span>