@quazardous/qdadm 1.19.3

package/src/index.ts

@@ -0,0 +1,453 @@
+/**
+ * qdadm - Vue 3 Admin Dashboard Framework
+ *
+ * A framework for building admin dashboards with Vue 3, PrimeVue, and Vue Router.
+ */
+
+// Version (from package.json)
+import pkg from '../package.json'
+export const version: string = (pkg as { version: string }).version
+
+// ════════════════════════════════════════════════════════════════════════════
+// KERNEL (simplified bootstrap) - Module, Kernel, KernelContext, SignalBus, etc.
+// ════════════════════════════════════════════════════════════════════════════
+export { Kernel } from './kernel/Kernel'
+export type {
+  AuthAdapter,
+  AppConfig,
+  Features,
+  Pages,
+  LayoutComponents,
+  PrimeVueConfig,
+  SecurityConfig,
+  SSEConfig,
+  DebugBarConfig,
+  NotificationsConfig,
+  HomeRoute,
+  KernelOptions,
+} from './kernel/Kernel'
+export { SignalBus, createSignalBus, SIGNALS, SIGNAL_ACTIONS, buildSignal } from './kernel/SignalBus'
+export type { SignalBusOptions, SignalAction, EntitySignalPayload } from './kernel/SignalBus'
+export { EventRouter, createEventRouter } from './kernel/EventRouter'
+export type {
+  SignalTarget,
+  RouteContext,
+  RouteCallback,
+  RouteTarget,
+  RoutesConfig,
+  EventRouterOptions,
+} from './kernel/EventRouter'
+export { SSEBridge, createSSEBridge, SSE_SIGNALS } from './kernel/SSEBridge'
+export type { SSEBridgeOptions } from './kernel/SSEBridge'
+export { Module } from './kernel/Module'
+export { KernelContext, createKernelContext } from './kernel/KernelContext'
+export type {
+  NavItem,
+  ZoneOptions,
+  BlockConfig,
+  RouteOptions,
+  CrudPages,
+  CrudOptions,
+  ChildPageOptions,
+  UserEntityOptions,
+  PermissionMeta,
+  PermissionOptions,
+} from './kernel/KernelContext'
+export {
+  ModuleLoader,
+  createModuleLoader,
+  ModuleNotFoundError,
+  CircularDependencyError,
+  ModuleLoadError,
+} from './kernel/ModuleLoader'
+export type {
+  ModuleContext,
+  ModuleLike,
+  ObjectModuleDefinition,
+  ModuleClassConstructor,
+  LegacyInitApi,
+  LegacyInitFunction,
+  ModuleDefinition,
+} from './kernel/ModuleLoader'
+
+// ════════════════════════════════════════════════════════════════════════════
+// PLUGIN (manual bootstrap)
+// ════════════════════════════════════════════════════════════════════════════
+export {
+  createQdadm,
+  type QdadmOptions,
+  type QdadmPlugin,
+  type ToastService,
+  type AuthAdapter as PluginAuthAdapter,
+  type AppConfig as PluginAppConfig,
+  type FeaturesConfig,
+  type ModulesConfig,
+} from './plugin'
+
+// ════════════════════════════════════════════════════════════════════════════
+// ENTITY (EntityManager, storage adapters, auth adapters)
+// ════════════════════════════════════════════════════════════════════════════
+export {
+  EntityManager,
+  createEntityManager,
+  type EntityManagerOptions,
+  type EntityBadge,
+  type SeverityDescriptor,
+  type SeverityMapValue,
+  type SeverityMap,
+  type RoutingContext,
+  type PresaveContext,
+  type PostsaveContext,
+  type PredeleteContext,
+  type QueryOptions,
+  type WhitelistContext,
+  type CacheInfo,
+} from './entity/EntityManager'
+
+// Re-export core entity types
+export type {
+  EntityRecord,
+  ListParams,
+  ListResult,
+  FieldConfig,
+  ChildConfig,
+  ParentConfig,
+  RelationConfig,
+  NavConfig,
+  StorageCapabilities,
+} from './types'
+
+// Manager Factory
+export {
+  managerFactory,
+  defaultManagerResolver,
+  createManagerFactory,
+  createManagers,
+  type ManagerConfig,
+  type ManagerFactoryContext,
+  type ManagerResolver,
+} from './entity/factory'
+
+// Storage adapters
+export * from './entity/storage/index'
+
+// Entity auth adapters
+export * from './entity/auth'
+
+// ════════════════════════════════════════════════════════════════════════════
+// SESSION AUTH (user authentication)
+// ════════════════════════════════════════════════════════════════════════════
+export { LocalStorageSessionAuthAdapter } from './auth'
+export type {
+  LoginCredentials,
+  SessionData,
+  ISessionAuthAdapter,
+  AuthUser as SessionAuthUser,
+} from './auth'
+
+// ════════════════════════════════════════════════════════════════════════════
+// ORCHESTRATOR
+// ════════════════════════════════════════════════════════════════════════════
+export * from './orchestrator/index'
+
+// ════════════════════════════════════════════════════════════════════════════
+// COMPOSABLES (excluding types that conflict with other modules)
+// ════════════════════════════════════════════════════════════════════════════
+export { useBareForm, type UseBareFormOptions, type UseBareFormReturn } from './composables/useBareForm'
+export {
+  useBreadcrumb,
+  type UseBreadcrumbOptions,
+  type UseBreadcrumbReturn,
+  type BreadcrumbDisplayItem,
+} from './composables/useBreadcrumb'
+export {
+  useSemanticBreadcrumb,
+  computeSemanticBreadcrumb,
+  type SemanticBreadcrumbItem,
+} from './composables/useSemanticBreadcrumb'
+export { useDirtyState, type UseDirtyStateReturn } from './composables/useDirtyState'
+export {
+  useForm,
+  type UseFormOptions,
+  type UseFormReturn,
+  type FormAlterConfig,
+} from './composables/useForm'
+export {
+  useEntityItemFormPage,
+  useEntityItemFormPage as useFormPageBuilder,
+  type UseEntityItemFormPageOptions,
+  type UseEntityItemFormPageReturn,
+  type FieldDefinition,
+  type ResolvedFieldConfig,
+  type ActionConfig as FormActionConfig,
+  type FormPageProps,
+  type FormPageEvents,
+} from './composables/useEntityItemFormPage'
+export * from './composables/useJsonSyntax'
+export {
+  useListPage,
+  PAGE_SIZE_OPTIONS,
+  type UseListPageOptions,
+  type UseListPageReturn,
+  type ColumnConfig,
+  type FilterConfig,
+  type ActionConfig as ListActionConfig,
+  type ResolvedAction,
+  type HeaderActionConfig,
+  type ResolvedHeaderAction,
+  type CardConfig,
+  type SearchConfig,
+  type ListPageProps,
+  type ListPageEvents,
+  type BulkStatusActionReturn,
+} from './composables/useListPage'
+export {
+  usePageTitle,
+  type UsePageTitleReturn,
+  type TitleParts,
+  type TitleInput,
+} from './composables/usePageTitle'
+export { useApp, type UseAppReturn } from './composables/useApp'
+export { useAuth, type UseAuthReturn } from './composables/useAuth'
+export {
+  useEntityItemPage,
+  type UseEntityItemPageOptions,
+  type UseEntityItemPageReturn,
+  // ParentConfig already exported from types
+} from './composables/useEntityItemPage'
+export {
+  useEntityItemShowPage,
+  useEntityItemShowPage as useShowPageBuilder,
+  type UseEntityItemShowPageOptions,
+  type UseEntityItemShowPageReturn,
+  type FieldDefinition as ShowFieldDefinition,
+  type ResolvedFieldConfig as ShowResolvedFieldConfig,
+  type ActionConfig as ShowActionConfig,
+  type LazyActionConfig as ShowLazyActionConfig,
+  type ShowPageProps,
+  type ShowPageEvents,
+} from './composables/useEntityItemShowPage'
+export {
+  useNavContext,
+  type UseNavContextOptions,
+  type UseNavContextReturn,
+  type NavChainSegment,
+  type NavChainType,
+  type BreadcrumbItem,
+  type NavLinkItem,
+} from './composables/useNavContext'
+export {
+  useNavigation,
+  type UseNavigationReturn,
+  type NavSection,
+  // NavItem already exported from kernel
+} from './composables/useNavigation'
+export {
+  useUnsavedChangesGuard,
+  type UseUnsavedChangesGuardOptions,
+  type UseUnsavedChangesGuardReturn,
+  type GuardDialogState,
+} from './composables/useUnsavedChangesGuard'
+export { useGuardDialog, type GuardDialog } from './composables/useGuardStore'
+export { useSignals } from './composables/useSignals'
+export {
+  useZoneRegistry,
+  type UseZoneRegistryReturn,
+  type ZoneDefinition,
+  type ZoneInfo,
+  // BlockConfig & ZoneRegistry exported from zones
+} from './composables/useZoneRegistry'
+export { useHooks } from './composables/useHooks'
+export {
+  useLayoutResolver,
+  createLayoutComponents,
+  layoutMeta,
+  LAYOUT_TYPES,
+  type UseLayoutResolverOptions,
+  type UseLayoutResolverReturn,
+  type LayoutType,
+  type LayoutComponentsMap,
+  type LayoutComponentsInput,
+  type LayoutMeta,
+} from './composables/useLayoutResolver'
+export { useSSEBridge, type UseSSEBridgeReturn } from './composables/useSSEBridge'
+export {
+  useDeferred,
+  useDeferredValue,
+  DEFERRED_INJECTION_KEY,
+  type UseDeferredValueReturn,
+} from './composables/useDeferred'
+export {
+  useInfoBanner,
+  provideBannerStore,
+  createBannerStore,
+  type Banner,
+  type BannerOptions,
+  type BannerSeverity,
+  type BannerStore,
+} from './composables/useInfoBanner'
+export {
+  useUserImpersonator,
+  type UseUserImpersonatorOptions,
+  type UseUserImpersonatorReturn,
+  type UserRecord,
+} from './composables/useUserImpersonator'
+export { useCurrentEntity, type UseCurrentEntityReturn } from './composables/useCurrentEntity'
+export {
+  useOptionsLookup,
+  type UseOptionsLookupConfig,
+  type UseOptionsLookupReturn,
+  type OptionsLookupItem,
+  type OptionsDisplayMode,
+} from './composables/useOptionsLookup'
+export { useChildPage, type UseChildPageReturn } from './composables/useChildPage'
+export { useSidebarState, SIDEBAR_COLLAPSED_KEY } from './composables/useSidebarState'
+
+// ════════════════════════════════════════════════════════════════════════════
+// COMPONENTS
+// ════════════════════════════════════════════════════════════════════════════
+export * from './components/index'
+
+// ════════════════════════════════════════════════════════════════════════════
+// MODULE SYSTEM (excluding types that conflict)
+// ════════════════════════════════════════════════════════════════════════════
+export {
+  registry,
+  initModules,
+  setSectionOrder,
+  getRoutes,
+  getNavSections,
+  alterMenuSections,
+  isMenuAltered,
+  getRouteFamilies,
+  getEntityConfigs,
+  getEntityConfig,
+  getSiblingRoutes,
+  getChildRoutes,
+  isRouteInFamily,
+  resetRegistry,
+  type ModuleRouteMeta,
+  type ModuleRoute,
+  type NavItemWithSection,
+  type AddRoutesOptions,
+  type EntityConfig,
+  type ModuleInitContext,
+  type ModuleInitFunction,
+  type InitModulesOptions,
+  type MenuAlterContext,
+  // ParentConfig, NavItem, NavSection, ModuleDefinition - already exported
+} from './module/moduleRegistry'
+
+// ════════════════════════════════════════════════════════════════════════════
+// ZONES (ZoneRegistry class and zone constants)
+// ════════════════════════════════════════════════════════════════════════════
+export {
+  ZoneRegistry,
+  createZoneRegistry,
+  type BlockOperation,
+  type WrapperInfo,
+  type ZoneConfig,
+  type ZoneDefineOptions,
+  type ZoneListInfo,
+  type ZoneDetailInfo,
+  type ZoneInspection,
+  type ZoneRegistryOptions,
+  // BlockConfig - already exported from kernel
+} from './zones/ZoneRegistry'
+export {
+  ZONES,
+  LAYOUT_ZONES,
+  LIST_ZONES,
+  FORM_ZONES,
+  DASHBOARD_ZONES,
+  registerStandardZones,
+  getStandardZoneNames,
+} from './zones/zones'
+
+// ════════════════════════════════════════════════════════════════════════════
+// CHAIN (active navigation stack)
+// ════════════════════════════════════════════════════════════════════════════
+export * from './chain/index'
+
+// ════════════════════════════════════════════════════════════════════════════
+// HOOKS
+// ════════════════════════════════════════════════════════════════════════════
+export * from './hooks/index'
+
+// ════════════════════════════════════════════════════════════════════════════
+// DEFERRED (async service loading)
+// ════════════════════════════════════════════════════════════════════════════
+export * from './deferred/index'
+
+// ════════════════════════════════════════════════════════════════════════════
+// CORE (extension helpers)
+// ════════════════════════════════════════════════════════════════════════════
+export * from './core/index'
+
+// ════════════════════════════════════════════════════════════════════════════
+// QUERY (MongoDB-like filtering)
+// ════════════════════════════════════════════════════════════════════════════
+export * from './query/index'
+
+// ════════════════════════════════════════════════════════════════════════════
+// UTILS
+// ════════════════════════════════════════════════════════════════════════════
+export * from './utils/index'
+
+// ════════════════════════════════════════════════════════════════════════════
+// TOAST (signal-based notifications)
+// ════════════════════════════════════════════════════════════════════════════
+export * from './toast/index'
+
+// ════════════════════════════════════════════════════════════════════════════
+// NOTIFICATIONS (optional notification panel)
+// ════════════════════════════════════════════════════════════════════════════
+export * from './notifications/index'
+
+// ════════════════════════════════════════════════════════════════════════════
+// DEBUG - NOT exported here to enable tree-shaking.
+// Import from '@quazardous/qdadm/debug' separately when needed:
+//   import { debugBar, DebugModule } from '@quazardous/qdadm/debug'
+// ════════════════════════════════════════════════════════════════════════════
+
+// ════════════════════════════════════════════════════════════════════════════
+// I18N (schema-derived keys, pluggable providers, signal-driven locale)
+// ════════════════════════════════════════════════════════════════════════════
+export {
+  I18n,
+  MessagesRegistry,
+  Resolver,
+  snakeCaseToTitle,
+  InlineTranslationProvider,
+  defineStrategy,
+  resolveStrategy,
+  STRATEGIES,
+  LazyTranslationProvider,
+  IncrementalDomainProvider,
+  isDomainAwareProvider,
+  createYamlLoader,
+  createDefaultCoreProvider,
+  useI18n,
+  I18N_INJECTION_KEY,
+} from './i18n'
+export type {
+  AliasPattern,
+  CoreMessages,
+  EntityMessages,
+  I18nDeps,
+  I18nOptions,
+  KeyStrategy,
+  KeyStrategyName,
+  MessagesBundle,
+  MessagesNode,
+  NavMessages,
+  ResolveStep,
+  ResolveTrace,
+  TranslateParams,
+  TranslationProvider,
+} from './i18n'
+
+// ════════════════════════════════════════════════════════════════════════════
+// ASSETS
+// ════════════════════════════════════════════════════════════════════════════
+export { default as qdadmLogo } from './assets/logo.svg'

package/src/kernel/EventRouter.ts

@@ -0,0 +1,23 @@
+/**
+ * EventRouter — qdadm re-export.
+ *
+ * The actual implementation now lives in `@quazardous/qdcore` so it can be
+ * shared with qdcms. The legacy `orchestrator` constructor option (which was
+ * never actually read by any callback in qdadm) has been dropped; callers
+ * needing extras in `RouteContext` should use the new `context` option:
+ *
+ * ```ts
+ * createEventRouter({ signals, context: { orchestrator }, routes })
+ * // -> available inside callbacks as ctx.orchestrator
+ * ```
+ */
+
+export { EventRouter, createEventRouter } from '@quazardous/qdcore'
+export type {
+  SignalTarget,
+  RouteContext,
+  RouteCallback,
+  RouteTarget,
+  RoutesConfig,
+  EventRouterOptions,
+} from '@quazardous/qdcore'

package/src/kernel/Kernel.api.ts

@@ -0,0 +1,79 @@
+import type { AxiosLikeClient, AxiosError } from './Kernel.types'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Self = any
+
+/**
+ * Patch Kernel prototype with API client methods.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function applyApiMethods(KernelClass: { prototype: any }): void {
+  const proto = KernelClass.prototype as Self
+
+  /**
+   * Setup an axios client with automatic auth and error handling
+   */
+  proto.setupApiClient = function (this: Self, client: AxiosLikeClient): AxiosLikeClient {
+    const { authAdapter } = this.options
+    const signals = this.signals!
+    const debug = this.options.debug ?? false
+
+    client.interceptors.request.use(
+      (config) => {
+        if (authAdapter?.getToken) {
+          const token = authAdapter.getToken()
+          if (token) {
+            config.headers = config.headers || {}
+            config.headers.Authorization = `Bearer ${token}`
+          }
+        }
+        return config
+      },
+      (error) => Promise.reject(error)
+    )
+
+    client.interceptors.response.use(
+      (response) => response,
+      async (error: unknown) => {
+        const axiosError = error as AxiosError
+        const status = axiosError.response?.status
+        const url = axiosError.config?.url
+
+        await signals.emit('api:error', {
+          status,
+          message: axiosError.message,
+          url,
+          error: axiosError,
+        })
+
+        if (status === 401 || status === 403) {
+          if (debug) {
+            console.warn(
+              `[Kernel] API ${status} error on ${url}, emitting auth:expired`
+            )
+          }
+          await signals.emit('auth:expired', { status, url })
+        }
+
+        return Promise.reject(error)
+      }
+    )
+
+    this._apiClient = client
+    return client
+  }
+
+  /**
+   * Get the configured API client
+   */
+  proto.getApiClient = function (this: Self): AxiosLikeClient | null {
+    return this._apiClient
+  }
+
+  Object.defineProperty(KernelClass.prototype, 'api', {
+    get(this: Self): AxiosLikeClient | null {
+      return this._apiClient
+    },
+    configurable: true,
+  })
+}

package/src/kernel/Kernel.auth.ts

@@ -0,0 +1,120 @@
+import { authFactory, CompositeAuthAdapter } from '../entity/auth'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Self = any
+
+/**
+ * Patch Kernel prototype with auth-related methods.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function applyAuthMethods(KernelClass: { prototype: any }): void {
+  const proto = KernelClass.prototype as Self
+
+  /**
+   * Resolve entityAuthAdapter through authFactory
+   */
+  proto._resolveEntityAuthAdapter = function (this: Self): void {
+    const { entityAuthAdapter, authTypes } = this.options
+
+    if (entityAuthAdapter == null) return
+
+    const context = {
+      authTypes: authTypes || {},
+      CompositeAuthAdapter,
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    this.options.entityAuthAdapter = authFactory(entityAuthAdapter, context as any)
+  }
+
+  /**
+   * Register auth:ready deferred if auth is configured
+   */
+  proto._registerAuthDeferred = function (this: Self): void {
+    const { authAdapter } = this.options
+    if (!authAdapter) return
+
+    this.deferred!.queue('auth:ready', () => {
+      return new Promise((resolve) => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        this.signals!.once('auth:login', (event: any) => {
+          resolve(event.data?.user)
+        })
+      })
+    })
+  }
+
+  /**
+   * Setup handler for auth:expired signal
+   */
+  proto._setupAuthExpiredHandler = function (this: Self): void {
+    const { authAdapter, onAuthExpired } = this.options
+    if (!authAdapter) return
+
+    this.signals!.on('auth:expired', async (payload: { data: unknown }) => {
+      const debug = this.options.debug ?? false
+      if (debug) {
+        console.warn('[Kernel] auth:expired received:', payload)
+      }
+
+      if (authAdapter.logout) {
+        authAdapter.logout()
+      }
+
+      const payloadData = typeof payload.data === 'object' && payload.data !== null ? payload.data : {}
+      await this.signals!.emit('auth:logout', { reason: 'expired', ...payloadData })
+
+      if (this.router!.currentRoute.value.name !== 'login') {
+        this.router!.push({ name: 'login', query: { expired: '1' } })
+      }
+
+      if (onAuthExpired) {
+        onAuthExpired(payload)
+      }
+    })
+  }
+
+  /**
+   * Setup authAdapter to react to impersonation signals
+   */
+  proto._setupAuthImpersonation = function (this: Self): void {
+    const { authAdapter } = this.options
+    if (!authAdapter?.connectSignals) return
+
+    const debug = this.options.debug ?? false
+    if (debug) {
+      console.debug('[Kernel] Wiring authAdapter.connectSignals() for impersonation')
+    }
+
+    this._authImpersonationCleanup = authAdapter.connectSignals(this.signals!)
+  }
+
+  /**
+   * Setup auth invalidation - remount entire app on auth changes
+   */
+  proto._setupAuthInvalidation = function (this: Self): void {
+    const debug = this.options.debug ?? false
+    const authSignals = [
+      'auth:login',
+      'auth:logout',
+      'auth:impersonate',
+      'auth:impersonate:stop',
+    ]
+
+    for (const signal of authSignals) {
+      this.signals!.on(signal, () => {
+        if (debug) {
+          console.debug(`[Kernel] ${signal} → invalidateApp()`)
+        }
+        this.invalidateApp()
+      })
+    }
+  }
+
+  /**
+   * Force full app remount
+   */
+  proto.invalidateApp = function (this: Self): void {
+    this._appKey.value++
+  }
+}