docs: resolve API hover to correct directory name

The Shiki transformer was mapping composable names to incorrect API
cache keys. For example, createStackPlugin mapped to createStack,
but the API cache key is useStack (the directory name).

Added V0_COMPOSABLE_TO_DIR mapping that maps each exported function
to its containing directory, which is used as the API cache key.

Author: johnleider

apps/docs/build/generate-api-whitelist.ts

@@ -46,9 +46,16 @@ async function getComponentNames (): Promise<string[]> {
  *
  * This automatically picks up any exported function matching composable patterns
  * (useX, createX, toX, provideX) without needing manual maintenance.
+ *
+ * Returns both a set of all names and a mapping from function name to directory name
+ * (the directory name is the API cache key).
  */
-async function getComposableNames (): Promise<string[]> {
+async function getComposableData (): Promise<{
+  names: string[]
+  toDir: Record<string, string>
+}> {
   const names = new Set<string>()
+  const toDir: Record<string, string> = {}
   const dirs = await readdir(COMPOSABLES_DIR)
 
   // Pattern for composable function names we care about
@@ -69,29 +76,41 @@ async function getComposableNames (): Promise<string[]> {
       const fnName = match[1]
       if (COMPOSABLE_PATTERN.test(fnName)) {
         names.add(fnName)
+        toDir[fnName] = dir
       }
     }
 
     // Also add the directory name itself (the primary export)
     names.add(dir)
+    toDir[dir] = dir
   }
 
   // Add trinity return values that are commonly used
   names.add('useContext')
   names.add('provideContext')
+  toDir['useContext'] = 'createContext'
+  toDir['provideContext'] = 'createContext'
 
-  return Array.from(names).toSorted()
+  return {
+    names: Array.from(names).toSorted(),
+    toDir,
+  }
 }
 
 /**
  * Generate the whitelist TypeScript file
  */
 export async function generateApiWhitelist (): Promise<void> {
-  const [components, composables] = await Promise.all([
+  const [components, composableData] = await Promise.all([
     getComponentNames(),
-    getComposableNames(),
+    getComposableData(),
   ])
 
+  const { names: composables, toDir } = composableData
+
+  // Sort toDir entries for stable output
+  const toDirEntries = Object.entries(toDir).toSorted((a, b) => a[0].localeCompare(b[0]))
+
   const content = `/**
  * AUTO-GENERATED - DO NOT EDIT
  *
@@ -120,6 +139,14 @@ ${components.map(c => `  '${c}',`).join('\n')}
 export const V0_COMPOSABLES = new Set([
 ${composables.map(c => `  '${c}',`).join('\n')}
 ])
+
+/**
+ * Maps composable function names to their directory name (API cache key).
+ * Used by the shiki-api-transformer to resolve the correct API page.
+ */
+export const V0_COMPOSABLE_TO_DIR: Record<string, string> = {
+${toDirEntries.map(([fn, dir]) => `  '${fn}': '${dir}',`).join('\n')}
+}
 `
 
   // Only write if content changed to avoid triggering Vite's file watcher loop

apps/docs/build/shiki-api-transformer.ts

@@ -13,7 +13,7 @@
 import type { ShikiTransformer } from 'shiki'
 
 // Auto-generated whitelists from packages/0/src/
-import { V0_COMPONENTS, V0_COMPOSABLES } from './generated/api-whitelist'
+import { V0_COMPONENTS, V0_COMPOSABLES, V0_COMPOSABLE_TO_DIR } from './generated/api-whitelist'
 // Vue API content - import only keys for build-time detection
 import { VUE_API_CONTENT } from './vue-api-content'
 
@@ -34,15 +34,18 @@ const TRINITY_RETURNS: Record<string, string> = {
 const VUE_API_NAMES = new Set(Object.keys(VUE_API_CONTENT))
 
 /**
- * Maps composable names to their canonical API page.
+ * Maps composable names to their canonical API page (directory name).
  * Returns the API name if valid, null otherwise.
  *
- * Patterns:
- * - createX -> createX (the canonical API page)
- * - useX -> createX (trinity return maps to factory)
- * - createXContext -> createX (variant maps to base)
- * - createXPlugin -> createX or useX (createStackPlugin -> createStack, createStoragePlugin -> useStorage)
- * - useContext/provideContext -> createContext (special trinity returns)
+ * Uses the V0_COMPOSABLE_TO_DIR mapping generated from source directories.
+ * Each function name maps to its containing directory, which is the API cache key.
+ *
+ * Examples:
+ * - createStackPlugin -> useStack (the directory containing it)
+ * - createStackContext -> useStack
+ * - useStack -> useStack
+ * - createSelection -> createSelection
+ * - useContext -> createContext (trinity return value)
  */
 function resolveComposable (name: string): { apiName: string } | null {
   // Check special trinity return values first (e.g., useContext -> createContext)
@@ -56,36 +59,13 @@ function resolveComposable (name: string): { apiName: string } | null {
     return null
   }
 
-  // For useX, check if createX exists (trinity pattern)
-  // useStack -> createStack, useGroup -> createGroup
-  if (name.startsWith('use')) {
-    const base = name.slice(3) // 'useStack' -> 'Stack'
-    const createVersion = `create${base}`
-    if (V0_COMPOSABLES.has(createVersion)) {
-      return { apiName: createVersion }
-    }
-  }
-
-  // For createXContext/createXPlugin, map to createX or useX
-  // createStackPlugin -> createStack, createStoragePlugin -> useStorage
-  if (name.startsWith('create')) {
-    const withoutPrefix = name.slice(6) // 'createStackPlugin' -> 'StackPlugin'
-    const base = withoutPrefix.replace(/(Plugin|Context)$/, '')
-    if (base && base !== withoutPrefix) {
-      // Try createX first (trinity factories)
-      const createVersion = `create${base}`
-      if (V0_COMPOSABLES.has(createVersion)) {
-        return { apiName: createVersion }
-      }
-      // Fall back to useX (plugin composables like useStorage, useTheme)
-      const useVersion = `use${base}`
-      if (V0_COMPOSABLES.has(useVersion)) {
-        return { apiName: useVersion }
-      }
-    }
+  // Use the mapping to get the directory name (API cache key)
+  const dirName = V0_COMPOSABLE_TO_DIR[name]
+  if (dirName) {
+    return { apiName: dirName }
   }
 
-  // Direct match - use as-is (createX, toX, etc.)
+  // Fallback: use the name as-is (shouldn't happen if whitelist is in sync)
   return { apiName: name }
 }