@quazardous/qdadm 1.19.3

package/src/composables/useUserImpersonator.ts

@@ -0,0 +1,317 @@
+/**
+ * useUserImpersonator - User impersonation composable
+ *
+ * Provides state and actions for user impersonation.
+ * Useful for admin dashboards to test permission-based UI as different users.
+ *
+ * Permission check:
+ *   - Requires 'auth:impersonate' permission (check via entityAuthAdapter.isGranted())
+ *   - Falls back to true if no entityAuthAdapter
+ *
+ * Signals emitted:
+ *   - auth:impersonate({ target, original }) - when impersonation starts
+ *   - auth:impersonate:stop({ original }) - when impersonation ends
+ *
+ * Usage:
+ *   // With users entity
+ *   const { isImpersonating, users, impersonate, exit } = useUserImpersonator({ entity: 'users' })
+ *
+ *   // With direct users list
+ *   const { isImpersonating, impersonate, exit } = useUserImpersonator({ users: myUsersList })
+ *
+ *   // Custom user mapping
+ *   const { ... } = useUserImpersonator({
+ *     entity: 'users',
+ *     userKey: 'uuid',        // default: 'id'
+ *     userLabel: 'email',     // default: 'username'
+ *   })
+ */
+
+import {
+  ref,
+  computed,
+  onMounted,
+  inject,
+  getCurrentInstance,
+  unref,
+  type Ref,
+  type ComputedRef,
+} from 'vue'
+import type { SignalBus } from '../kernel/SignalBus'
+
+/**
+ * User record type
+ */
+export interface UserRecord {
+  [key: string]: unknown
+  role?: string
+}
+
+/**
+ * Auth adapter interface for impersonation
+ */
+interface AuthAdapterWithImpersonation {
+  getUser?: () => UserRecord | null
+  getOriginalUser?: () => UserRecord | null
+}
+
+/**
+ * Entity auth adapter interface
+ */
+interface EntityAuthAdapter {
+  isGranted?: (permission: string) => boolean
+}
+
+/**
+ * Orchestrator interface
+ */
+interface Orchestrator {
+  signals?: SignalBus
+  entityAuthAdapter?: EntityAuthAdapter
+  get: (entityName: string) => EntityManager | null
+}
+
+/**
+ * Entity manager interface
+ */
+interface EntityManager {
+  findAll: () => Promise<{ data?: UserRecord[] } | UserRecord[]>
+}
+
+/**
+ * Options for useUserImpersonator
+ */
+export interface UseUserImpersonatorOptions {
+  /** Entity name to fetch users from (e.g., 'users') */
+  entity?: string
+  /** Direct users list (reactive or static) */
+  users?: UserRecord[] | Ref<UserRecord[]>
+  /** Field to use as user ID (default: 'id') */
+  userKey?: string
+  /** Field to use as user display label (default: 'username') */
+  userLabel?: string
+  /** Permission to check for impersonation (default: 'auth:impersonate') */
+  permission?: string
+}
+
+/**
+ * Return type for useUserImpersonator
+ */
+export interface UseUserImpersonatorReturn {
+  // State
+  users: Ref<UserRecord[]>
+  loading: Ref<boolean>
+  error: Ref<string | null>
+  currentUser: ComputedRef<UserRecord | null>
+  originalUser: ComputedRef<UserRecord | null>
+  isImpersonating: ComputedRef<boolean>
+  canImpersonate: ComputedRef<boolean>
+  availableUsers: ComputedRef<UserRecord[]>
+
+  // Actions
+  impersonate: (userOrId: UserRecord | string | number) => Promise<void>
+  exitImpersonation: () => Promise<void>
+  exit: () => Promise<void>
+  loadUsers: () => Promise<void>
+
+  // Config
+  userKey: string
+  userLabel: string
+}
+
+/**
+ * User impersonation composable
+ *
+ * @param options - Configuration options
+ * @returns Impersonation state and actions
+ */
+export function useUserImpersonator(
+  options: UseUserImpersonatorOptions = {}
+): UseUserImpersonatorReturn {
+  // Strict context check - must be called in component setup()
+  const instance = getCurrentInstance()
+  if (!instance) {
+    throw new Error('[qdadm] useUserImpersonator() must be called within component setup()')
+  }
+
+  const {
+    entity,
+    users: providedUsers,
+    userKey = 'id',
+    userLabel = 'username',
+    permission = 'auth:impersonate',
+  } = options
+
+  const orchestrator = inject<Orchestrator | null>('qdadmOrchestrator', null)
+  const authAdapter = inject<AuthAdapterWithImpersonation | null>('authAdapter', null)
+  const signals = orchestrator?.signals || null
+  const entityAuth = orchestrator?.entityAuthAdapter || null
+
+  // State
+  const users = ref<UserRecord[]>([])
+  const loading = ref(false)
+  const error = ref<string | null>(null)
+
+  // Note: authTick removed - Kernel.invalidateApp() remounts entire app
+  // on auth changes, so composable is re-initialized with fresh state
+
+  /**
+   * Current user (may be impersonated)
+   */
+  const currentUser = computed(() => {
+    return authAdapter?.getUser?.() || null
+  })
+
+  /**
+   * Original user (before impersonation)
+   */
+  const originalUser = computed(() => {
+    return authAdapter?.getOriginalUser?.() || null
+  })
+
+  /**
+   * Currently impersonating another user
+   */
+  const isImpersonating = computed(() => {
+    return originalUser.value !== null
+  })
+
+  /**
+   * Check if current user can impersonate others
+   */
+  const canImpersonate = computed(() => {
+    if (!entityAuth?.isGranted) return true // Default allow if no auth
+    return entityAuth.isGranted(permission)
+  })
+
+  /**
+   * Users available for impersonation
+   * Excludes: original admin AND currently impersonated user
+   * Returns full user objects (not just id/label) so role is preserved
+   */
+  const availableUsers = computed(() => {
+    const excludeIds = new Set<unknown>()
+    if (originalUser.value?.[userKey]) excludeIds.add(originalUser.value[userKey])
+    if (currentUser.value?.[userKey]) excludeIds.add(currentUser.value[userKey])
+
+    return users.value.filter((u) => !excludeIds.has(u[userKey]))
+  })
+
+  /**
+   * Load users from entity or provided list
+   */
+  async function loadUsers(): Promise<void> {
+    // If users provided directly, use them
+    if (providedUsers) {
+      users.value = unref(providedUsers)
+      return
+    }
+
+    // Load from entity
+    if (entity && orchestrator) {
+      try {
+        loading.value = true
+        error.value = null
+        const manager = orchestrator.get(entity)
+        if (manager) {
+          const result = await manager.findAll()
+          users.value =
+            (result as { data?: UserRecord[] })?.data ||
+            (result as UserRecord[]) ||
+            ([] as UserRecord[])
+        }
+      } catch (e) {
+        error.value = (e as Error).message
+        console.warn(`[qdadm] useUserImpersonator: Failed to load users from ${entity}:`, e)
+      } finally {
+        loading.value = false
+      }
+    }
+  }
+
+  /**
+   * Start impersonating a user
+   *
+   * @param userOrId - User object or user ID to impersonate
+   */
+  async function impersonate(userOrId: UserRecord | string | number): Promise<void> {
+    if (!canImpersonate.value) {
+      console.warn('[qdadm] useUserImpersonator: No permission to impersonate')
+      return
+    }
+
+    // Resolve user object
+    let targetUser: UserRecord | undefined
+    if (typeof userOrId === 'object') {
+      targetUser = userOrId
+    } else {
+      // Find user by ID
+      targetUser = users.value.find((u) => u[userKey] === userOrId)
+    }
+
+    if (!targetUser) {
+      console.warn('[qdadm] useUserImpersonator: User not found')
+      return
+    }
+
+    // Get current user for signal payload
+    const original = authAdapter?.getUser?.()
+
+    // Build target user object with essential fields
+    const impersonatedUser: UserRecord = {
+      [userKey]: targetUser[userKey],
+      [userLabel]: targetUser[userLabel],
+      role: targetUser.role, // Include role if present
+    }
+
+    // Emit auth:impersonate signal - authAdapter reacts via connectSignals()
+    await signals?.emit('auth:impersonate', {
+      target: impersonatedUser,
+      original,
+    })
+  }
+
+  /**
+   * Exit impersonation and restore original user
+   */
+  async function exitImpersonation(): Promise<void> {
+    if (!isImpersonating.value) return
+
+    // Get original user for signal payload
+    const original = authAdapter?.getOriginalUser?.()
+
+    // Emit auth:impersonate:stop signal - authAdapter reacts via connectSignals()
+    await signals?.emit('auth:impersonate:stop', {
+      original,
+    })
+  }
+
+  // Load users on mount
+  // Note: Auth signal listeners removed - Kernel.invalidateApp() remounts entire app
+  // on auth changes, so composable is re-initialized with fresh state
+  onMounted(() => {
+    loadUsers()
+  })
+
+  return {
+    // State
+    users,
+    loading,
+    error,
+    currentUser,
+    originalUser,
+    isImpersonating,
+    canImpersonate,
+    availableUsers,
+
+    // Actions
+    impersonate,
+    exitImpersonation,
+    exit: exitImpersonation, // Alias
+    loadUsers,
+
+    // Config (for template binding)
+    userKey,
+    userLabel,
+  }
+}

package/src/composables/useZoneRegistry.ts

@@ -0,0 +1,252 @@
+/**
+ * useZoneRegistry - Access the zone registry for extensible UI composition
+ *
+ * Provides reactive access to the ZoneRegistry created by Kernel during bootstrap.
+ * Components can register/unregister blocks and query zones reactively.
+ *
+ * **Reactivity**: The registry is reactive. When blocks are added, removed, or modified,
+ * components using `getBlocks()` will automatically re-render.
+ *
+ * @returns Object with registry methods and reactive helpers
+ * @throws Error if zone registry is not available (Kernel not initialized)
+ *
+ * @example
+ * // Basic access to zones (reactive)
+ * import { useZoneRegistry } from '@quazardous/qdadm'
+ * import { ZONES } from '@quazardous/qdadm/zones'
+ *
+ * const { getBlocks, registerBlock, unregisterBlock } = useZoneRegistry()
+ *
+ * // Get blocks (reactive - component re-renders when blocks change)
+ * const headerBlocks = computed(() => getBlocks(ZONES.HEADER))
+ *
+ * @example
+ * // Register/unregister blocks at component lifecycle
+ * import { useZoneRegistry } from '@quazardous/qdadm'
+ * import { ZONES } from '@quazardous/qdadm/zones'
+ * import AdBanner from './AdBanner.vue'
+ *
+ * const { registerBlock, unregisterBlock } = useZoneRegistry()
+ *
+ * onMounted(() => {
+ *   registerBlock(ZONES.SIDEBAR, {
+ *     id: 'ad-banner',
+ *     component: AdBanner,
+ *     weight: 50,
+ *     props: { variant: 'compact' }
+ *   })
+ * })
+ *
+ * onUnmounted(() => {
+ *   unregisterBlock(ZONES.SIDEBAR, 'ad-banner')
+ * })
+ *
+ * @example
+ * // Conditional block registration based on feature flag
+ * import { useZoneRegistry } from '@quazardous/qdadm'
+ * import { watch } from 'vue'
+ *
+ * const { registerBlock, unregisterBlock } = useZoneRegistry()
+ *
+ * watch(featureEnabled, (enabled) => {
+ *   if (enabled) {
+ *     registerBlock('sidebar', { id: 'feature-widget', component: FeatureWidget })
+ *   } else {
+ *     unregisterBlock('sidebar', 'feature-widget')
+ *   }
+ * }, { immediate: true })
+ *
+ * @example
+ * // Direct registry access
+ * const { registry } = useZoneRegistry()
+ * const zones = registry.listZones()
+ * console.log('Available zones:', zones)
+ */
+import { inject, computed, type ComputedRef, type Component, type Ref } from 'vue'
+
+/**
+ * Block configuration for zone registration
+ */
+export interface BlockConfig {
+  /** Unique block identifier */
+  id: string
+  /** Vue component to render */
+  component: Component
+  /** Sort weight (lower = first) */
+  weight?: number
+  /** Props to pass to component */
+  props?: Record<string, unknown>
+  /** Additional config */
+  [key: string]: unknown
+}
+
+/**
+ * Zone definition
+ */
+export interface ZoneDefinition {
+  /** Zone name */
+  name: string
+  /** Default component if no blocks registered */
+  default?: Component
+  /** Zone description */
+  description?: string
+}
+
+/**
+ * Zone info
+ */
+export interface ZoneInfo {
+  name: string
+  blockCount: number
+  hasDefault: boolean
+}
+
+/**
+ * Zone registry interface
+ */
+export interface ZoneRegistry {
+  getVersionRef: () => Ref<number>
+  getBlocks: (zoneName: string) => BlockConfig[]
+  registerBlock: (zoneName: string, blockConfig: BlockConfig) => ZoneRegistry
+  unregisterBlock: (zoneName: string, blockId: string) => boolean
+  defineZone: (zoneName: string, definition?: ZoneDefinition) => ZoneRegistry
+  hasBlocks: (zoneName: string) => boolean
+  hasZone: (zoneName: string) => boolean
+  getDefault: (zoneName: string) => Component | null
+  listZones: () => string[]
+  getZoneInfo: (zoneName: string) => ZoneInfo | null
+  inspect: () => Record<string, BlockConfig[]>
+}
+
+/**
+ * Return type for useZoneRegistry
+ */
+export interface UseZoneRegistryReturn {
+  /** Direct registry access for advanced usage */
+  registry: ZoneRegistry
+
+  /** Get blocks for a zone (reactive) */
+  getBlocks: (zoneName: string) => BlockConfig[]
+  /** Create a computed ref for a zone's blocks */
+  useBlocks: (zoneName: string) => ComputedRef<BlockConfig[]>
+
+  /** Register a block in a zone */
+  registerBlock: (zoneName: string, blockConfig: BlockConfig) => ZoneRegistry
+  /** Unregister a block from a zone */
+  unregisterBlock: (zoneName: string, blockId: string) => boolean
+
+  /** Define a new zone */
+  defineZone: (zoneName: string, definition?: ZoneDefinition) => ZoneRegistry
+  /** Check if zone has any blocks */
+  hasBlocks: (zoneName: string) => boolean
+  /** Check if zone exists */
+  hasZone: (zoneName: string) => boolean
+  /** Get default component for zone */
+  getDefault: (zoneName: string) => Component | null
+  /** List all zone names */
+  listZones: () => string[]
+  /** Get zone info */
+  getZoneInfo: (zoneName: string) => ZoneInfo | null
+  /** Inspect all zones and blocks */
+  inspect: () => Record<string, BlockConfig[]>
+}
+
+export function useZoneRegistry(): UseZoneRegistryReturn {
+  const injectedRegistry = inject<ZoneRegistry | null>('qdadmZoneRegistry', null)
+
+  if (!injectedRegistry) {
+    throw new Error('[qdadm] Zone registry not provided. Ensure Kernel is initialized.')
+  }
+
+  // Non-null after check above
+  const registry = injectedRegistry
+
+  // Get the reactive version ref for tracking changes
+  const version = registry.getVersionRef()
+
+  /**
+   * Get blocks for a zone (reactive)
+   *
+   * This function depends on the registry's version counter,
+   * so it will return fresh data when blocks change.
+   *
+   * @param zoneName - Zone name
+   * @returns Array of block configs
+   */
+  function getBlocks(zoneName: string): BlockConfig[] {
+    // Access version.value to create reactive dependency
+    // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+    version.value
+    return registry.getBlocks(zoneName)
+  }
+
+  /**
+   * Create a computed ref for a zone's blocks
+   *
+   * Convenience method for creating a reactive computed ref
+   * that updates when the zone's blocks change.
+   *
+   * @param zoneName - Zone name
+   * @returns Computed ref of blocks
+   *
+   * @example
+   * const headerBlocks = useBlocks(ZONES.HEADER)
+   * // headerBlocks.value is reactive array
+   */
+  function useBlocks(zoneName: string): ComputedRef<BlockConfig[]> {
+    return computed(() => {
+      // Access version to create dependency
+      // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+      version.value
+      return registry.getBlocks(zoneName)
+    })
+  }
+
+  /**
+   * Register a block in a zone
+   *
+   * Proxy to registry.registerBlock() for convenience.
+   *
+   * @param zoneName - Target zone name
+   * @param blockConfig - Block configuration
+   * @returns The registry (for chaining)
+   */
+  function registerBlock(zoneName: string, blockConfig: BlockConfig): ZoneRegistry {
+    return registry.registerBlock(zoneName, blockConfig)
+  }
+
+  /**
+   * Unregister a block from a zone
+   *
+   * Proxy to registry.unregisterBlock() for convenience.
+   *
+   * @param zoneName - Zone name
+   * @param blockId - Block ID to unregister
+   * @returns True if block was found and removed
+   */
+  function unregisterBlock(zoneName: string, blockId: string): boolean {
+    return registry.unregisterBlock(zoneName, blockId)
+  }
+
+  return {
+    // Direct registry access for advanced usage
+    registry,
+
+    // Reactive helpers
+    getBlocks,
+    useBlocks,
+
+    // Block management
+    registerBlock,
+    unregisterBlock,
+
+    // Passthrough common methods
+    defineZone: registry.defineZone.bind(registry),
+    hasBlocks: registry.hasBlocks.bind(registry),
+    hasZone: registry.hasZone.bind(registry),
+    getDefault: registry.getDefault.bind(registry),
+    listZones: registry.listZones.bind(registry),
+    getZoneInfo: registry.getZoneInfo.bind(registry),
+    inspect: registry.inspect.bind(registry),
+  }
+}