qdadm 0.13.0

package/src/entity/storage/LocalStorage.js

@@ -0,0 +1,220 @@
+/**
+ * LocalStorage - Browser localStorage storage adapter
+ *
+ * Implements the storage interface using browser localStorage.
+ * Useful for:
+ * - Offline-first applications
+ * - User preferences
+ * - Draft saving
+ * - Small datasets that persist across sessions
+ *
+ * Usage:
+ * ```js
+ * const storage = new LocalStorage({
+ *   key: 'my_entities',
+ *   idField: 'id',
+ *   generateId: () => crypto.randomUUID()
+ * })
+ * ```
+ */
+export class LocalStorage {
+  constructor(options = {}) {
+    const {
+      key,
+      idField = 'id',
+      generateId = () => Date.now().toString(36) + Math.random().toString(36).substr(2)
+    } = options
+
+    this.key = key
+    this.idField = idField
+    this.generateId = generateId
+  }
+
+  /**
+   * Get all items from localStorage
+   * @returns {Array}
+   */
+  _getAll() {
+    try {
+      const stored = localStorage.getItem(this.key)
+      return stored ? JSON.parse(stored) : []
+    } catch {
+      return []
+    }
+  }
+
+  /**
+   * Save all items to localStorage
+   * @param {Array} items
+   */
+  _saveAll(items) {
+    localStorage.setItem(this.key, JSON.stringify(items))
+  }
+
+  /**
+   * List entities with pagination/filtering
+   * @param {object} params - { page, page_size, sort_by, sort_order, ...filters }
+   * @returns {Promise<{ items: Array, total: number }>}
+   */
+  async list(params = {}) {
+    const { page = 1, page_size = 20, sort_by, sort_order = 'asc', ...filters } = params
+
+    let items = this._getAll()
+
+    // Apply filters
+    for (const [key, value] of Object.entries(filters)) {
+      if (value === null || value === undefined || value === '') continue
+      items = items.filter(item => {
+        const itemValue = item[key]
+        if (typeof value === 'string' && typeof itemValue === 'string') {
+          return itemValue.toLowerCase().includes(value.toLowerCase())
+        }
+        return itemValue === value
+      })
+    }
+
+    const total = items.length
+
+    // Apply sorting
+    if (sort_by) {
+      items.sort((a, b) => {
+        const aVal = a[sort_by]
+        const bVal = b[sort_by]
+        if (aVal < bVal) return sort_order === 'asc' ? -1 : 1
+        if (aVal > bVal) return sort_order === 'asc' ? 1 : -1
+        return 0
+      })
+    }
+
+    // Apply pagination
+    const start = (page - 1) * page_size
+    items = items.slice(start, start + page_size)
+
+    return { items, total }
+  }
+
+  /**
+   * Get a single entity by ID
+   * @param {string|number} id
+   * @returns {Promise<object>}
+   */
+  async get(id) {
+    const items = this._getAll()
+    const item = items.find(i => i[this.idField] === id)
+    if (!item) {
+      const error = new Error(`Entity not found: ${id}`)
+      error.status = 404
+      throw error
+    }
+    return item
+  }
+
+  /**
+   * Get multiple entities by IDs (batch fetch)
+   * @param {Array<string|number>} ids
+   * @returns {Promise<Array<object>>}
+   */
+  async getMany(ids) {
+    if (!ids || ids.length === 0) return []
+    const items = this._getAll()
+    const idSet = new Set(ids)
+    return items.filter(i => idSet.has(i[this.idField]))
+  }
+
+  /**
+   * Create a new entity
+   * @param {object} data
+   * @returns {Promise<object>}
+   */
+  async create(data) {
+    const items = this._getAll()
+    const newItem = {
+      ...data,
+      [this.idField]: data[this.idField] || this.generateId(),
+      created_at: data.created_at || new Date().toISOString()
+    }
+    items.push(newItem)
+    this._saveAll(items)
+    return newItem
+  }
+
+  /**
+   * Update an entity (PUT - full replacement)
+   * @param {string|number} id
+   * @param {object} data
+   * @returns {Promise<object>}
+   */
+  async update(id, data) {
+    const items = this._getAll()
+    const index = items.findIndex(i => i[this.idField] === id)
+    if (index === -1) {
+      const error = new Error(`Entity not found: ${id}`)
+      error.status = 404
+      throw error
+    }
+    const updated = {
+      ...data,
+      [this.idField]: id,
+      updated_at: new Date().toISOString()
+    }
+    items[index] = updated
+    this._saveAll(items)
+    return updated
+  }
+
+  /**
+   * Partially update an entity (PATCH)
+   * @param {string|number} id
+   * @param {object} data
+   * @returns {Promise<object>}
+   */
+  async patch(id, data) {
+    const items = this._getAll()
+    const index = items.findIndex(i => i[this.idField] === id)
+    if (index === -1) {
+      const error = new Error(`Entity not found: ${id}`)
+      error.status = 404
+      throw error
+    }
+    const updated = {
+      ...items[index],
+      ...data,
+      updated_at: new Date().toISOString()
+    }
+    items[index] = updated
+    this._saveAll(items)
+    return updated
+  }
+
+  /**
+   * Delete an entity
+   * @param {string|number} id
+   * @returns {Promise<void>}
+   */
+  async delete(id) {
+    const items = this._getAll()
+    const index = items.findIndex(i => i[this.idField] === id)
+    if (index === -1) {
+      const error = new Error(`Entity not found: ${id}`)
+      error.status = 404
+      throw error
+    }
+    items.splice(index, 1)
+    this._saveAll(items)
+  }
+
+  /**
+   * Clear all items
+   * @returns {Promise<void>}
+   */
+  async clear() {
+    localStorage.removeItem(this.key)
+  }
+}
+
+/**
+ * Factory function to create a LocalStorage
+ */
+export function createLocalStorage(options) {
+  return new LocalStorage(options)
+}

package/src/entity/storage/MemoryStorage.js

@@ -0,0 +1,201 @@
+/**
+ * MemoryStorage - In-memory storage adapter
+ *
+ * Implements the storage interface using in-memory Map.
+ * Useful for:
+ * - Testing
+ * - Ephemeral data
+ * - Caching layer
+ * - Client-side state management
+ *
+ * Usage:
+ * ```js
+ * const storage = new MemoryStorage({
+ *   idField: 'id',
+ *   generateId: () => crypto.randomUUID(),
+ *   initialData: [{ id: '1', name: 'Alice' }]
+ * })
+ * ```
+ */
+export class MemoryStorage {
+  constructor(options = {}) {
+    const {
+      idField = 'id',
+      generateId = () => Date.now().toString(36) + Math.random().toString(36).substr(2),
+      initialData = []
+    } = options
+
+    this.idField = idField
+    this.generateId = generateId
+    this._data = new Map()
+
+    // Initialize with initial data
+    for (const item of initialData) {
+      const id = item[idField]
+      if (id) {
+        this._data.set(String(id), { ...item })
+      }
+    }
+  }
+
+  /**
+   * Get all items as array
+   * @returns {Array}
+   */
+  _getAll() {
+    return Array.from(this._data.values())
+  }
+
+  /**
+   * List entities with pagination/filtering
+   * @param {object} params - { page, page_size, sort_by, sort_order, ...filters }
+   * @returns {Promise<{ items: Array, total: number }>}
+   */
+  async list(params = {}) {
+    const { page = 1, page_size = 20, sort_by, sort_order = 'asc', ...filters } = params
+
+    let items = this._getAll()
+
+    // Apply filters
+    for (const [key, value] of Object.entries(filters)) {
+      if (value === null || value === undefined || value === '') continue
+      items = items.filter(item => {
+        const itemValue = item[key]
+        if (typeof value === 'string' && typeof itemValue === 'string') {
+          return itemValue.toLowerCase().includes(value.toLowerCase())
+        }
+        return itemValue === value
+      })
+    }
+
+    const total = items.length
+
+    // Apply sorting
+    if (sort_by) {
+      items.sort((a, b) => {
+        const aVal = a[sort_by]
+        const bVal = b[sort_by]
+        if (aVal < bVal) return sort_order === 'asc' ? -1 : 1
+        if (aVal > bVal) return sort_order === 'asc' ? 1 : -1
+        return 0
+      })
+    }
+
+    // Apply pagination
+    const start = (page - 1) * page_size
+    items = items.slice(start, start + page_size)
+
+    return { items, total }
+  }
+
+  /**
+   * Get a single entity by ID
+   * @param {string|number} id
+   * @returns {Promise<object>}
+   */
+  async get(id) {
+    const item = this._data.get(String(id))
+    if (!item) {
+      const error = new Error(`Entity not found: ${id}`)
+      error.status = 404
+      throw error
+    }
+    return { ...item }
+  }
+
+  /**
+   * Create a new entity
+   * @param {object} data
+   * @returns {Promise<object>}
+   */
+  async create(data) {
+    const id = data[this.idField] || this.generateId()
+    const newItem = {
+      ...data,
+      [this.idField]: id,
+      created_at: data.created_at || new Date().toISOString()
+    }
+    this._data.set(String(id), newItem)
+    return { ...newItem }
+  }
+
+  /**
+   * Update an entity (PUT - full replacement)
+   * @param {string|number} id
+   * @param {object} data
+   * @returns {Promise<object>}
+   */
+  async update(id, data) {
+    if (!this._data.has(String(id))) {
+      const error = new Error(`Entity not found: ${id}`)
+      error.status = 404
+      throw error
+    }
+    const updated = {
+      ...data,
+      [this.idField]: id,
+      updated_at: new Date().toISOString()
+    }
+    this._data.set(String(id), updated)
+    return { ...updated }
+  }
+
+  /**
+   * Partially update an entity (PATCH)
+   * @param {string|number} id
+   * @param {object} data
+   * @returns {Promise<object>}
+   */
+  async patch(id, data) {
+    const existing = this._data.get(String(id))
+    if (!existing) {
+      const error = new Error(`Entity not found: ${id}`)
+      error.status = 404
+      throw error
+    }
+    const updated = {
+      ...existing,
+      ...data,
+      updated_at: new Date().toISOString()
+    }
+    this._data.set(String(id), updated)
+    return { ...updated }
+  }
+
+  /**
+   * Delete an entity
+   * @param {string|number} id
+   * @returns {Promise<void>}
+   */
+  async delete(id) {
+    if (!this._data.has(String(id))) {
+      const error = new Error(`Entity not found: ${id}`)
+      error.status = 404
+      throw error
+    }
+    this._data.delete(String(id))
+  }
+
+  /**
+   * Clear all items
+   * @returns {Promise<void>}
+   */
+  async clear() {
+    this._data.clear()
+  }
+
+  /**
+   * Get current item count
+   * @returns {number}
+   */
+  get size() {
+    return this._data.size
+  }
+}
+
+/**
+ * Factory function to create a MemoryStorage
+ */
+export function createMemoryStorage(options) {
+  return new MemoryStorage(options)
+}

package/src/entity/storage/index.js

@@ -0,0 +1,10 @@
+/**
+ * Storage Adapters
+ *
+ * Boilerplate implementations for common storage backends.
+ * EntityManagers can use these or implement their own storage.
+ */
+
+export { ApiStorage, createApiStorage } from './ApiStorage.js'
+export { LocalStorage, createLocalStorage } from './LocalStorage.js'
+export { MemoryStorage, createMemoryStorage } from './MemoryStorage.js'

package/src/index.js

@@ -0,0 +1,29 @@
+/**
+ * qdadm - Vue 3 Admin Dashboard Framework
+ *
+ * A framework for building admin dashboards with Vue 3, PrimeVue, and Vue Router.
+ */
+
+// Kernel (simplified bootstrap)
+export * from './kernel/index.js'
+
+// Plugin (manual bootstrap)
+export { createQdadm } from './plugin.js'
+
+// Entity system
+export * from './entity/index.js'
+
+// Orchestrator
+export * from './orchestrator/index.js'
+
+// Composables
+export * from './composables/index.js'
+
+// Components
+export * from './components/index.js'
+
+// Module system
+export * from './module/index.js'
+
+// Utils
+export * from './utils/index.js'

package/src/kernel/Kernel.js

@@ -0,0 +1,234 @@
+/**
+ * Kernel - Simplified bootstrap for qdadm applications
+ *
+ * Handles all the boilerplate:
+ * - Vue app creation
+ * - Pinia, PrimeVue, ToastService, ConfirmationService
+ * - Router with auth guard
+ * - Module discovery
+ * - qdadm plugin installation
+ *
+ * The constructor is purely declarative (stores config only).
+ * All initialization happens in createApp(), allowing you to:
+ * - Modify options before app creation
+ * - Add custom plugins/directives after createApp() but before mount()
+ *
+ * Basic usage:
+ * ```js
+ * const kernel = new Kernel({ root: App, managers, authAdapter, ... })
+ * kernel.createApp().mount('#app')
+ * ```
+ *
+ * Advanced usage (tweaking before/after):
+ * ```js
+ * const kernel = new Kernel({ ... })
+ *
+ * // Tweak config before app creation
+ * kernel.options.features.poweredBy = false
+ *
+ * // Create app
+ * const app = kernel.createApp()
+ *
+ * // Add custom plugins/components before mount
+ * app.component('MyGlobalComponent', MyComponent)
+ * app.directive('focus', focusDirective)
+ *
+ * app.mount('#app')
+ * ```
+ */
+
+import { createApp } from 'vue'
+import { createPinia } from 'pinia'
+import { createRouter, createWebHistory } from 'vue-router'
+import ToastService from 'primevue/toastservice'
+import ConfirmationService from 'primevue/confirmationservice'
+import Tooltip from 'primevue/tooltip'
+
+import { createQdadm } from '../plugin.js'
+import { initModules, getRoutes, setSectionOrder } from '../module/moduleRegistry.js'
+import { Orchestrator } from '../orchestrator/Orchestrator.js'
+
+export class Kernel {
+  /**
+   * @param {object} options
+   * @param {object} options.root - Root Vue component
+   * @param {object} options.modules - Result of import.meta.glob for module init files
+   * @param {string[]} options.sectionOrder - Navigation section order
+   * @param {object} options.managers - Entity managers { name: EntityManager }
+   * @param {object} options.authAdapter - Auth adapter for login/logout
+   * @param {object} options.pages - Page components { login, layout }
+   * @param {string} options.homeRoute - Route name for home redirect
+   * @param {object} options.app - App config { name, shortName, version, logo, theme }
+   * @param {object} options.features - Feature toggles { auth, poweredBy }
+   * @param {object} options.primevue - PrimeVue config { plugin, theme, options }
+   */
+  constructor(options) {
+    this.options = options
+    this.vueApp = null
+    this.router = null
+    this.orchestrator = null
+  }
+
+  /**
+   * Create and configure the Vue app
+   * @returns {App} Vue app instance ready to mount
+   */
+  createApp() {
+    this._initModules()
+    this._createRouter()
+    this._createOrchestrator()
+    this._createVueApp()
+    this._installPlugins()
+    return this.vueApp
+  }
+
+  /**
+   * Initialize modules from glob import
+   */
+  _initModules() {
+    if (this.options.sectionOrder) {
+      setSectionOrder(this.options.sectionOrder)
+    }
+    if (this.options.modules) {
+      initModules(this.options.modules)
+    }
+  }
+
+  /**
+   * Create Vue Router with auth guard
+   */
+  _createRouter() {
+    const { pages, homeRoute, authAdapter } = this.options
+
+    // Validate required pages
+    if (!pages?.login) {
+      throw new Error('[Kernel] pages.login is required')
+    }
+    if (!pages?.layout) {
+      throw new Error('[Kernel] pages.layout is required')
+    }
+
+    // Build routes
+    const routes = [
+      {
+        path: '/login',
+        name: 'login',
+        component: pages.login
+      },
+      {
+        path: '/',
+        component: pages.layout,
+        meta: { requiresAuth: true },
+        children: [
+          { path: '', redirect: { name: homeRoute || 'home' } },
+          ...getRoutes()
+        ]
+      }
+    ]
+
+    this.router = createRouter({
+      history: createWebHistory(),
+      routes
+    })
+
+    // Auth guard
+    if (authAdapter) {
+      this.router.beforeEach((to, from, next) => {
+        if (to.meta.requiresAuth && !authAdapter.isAuthenticated()) {
+          next({ name: 'login' })
+        } else {
+          next()
+        }
+      })
+    }
+  }
+
+  /**
+   * Create orchestrator with managers
+   */
+  _createOrchestrator() {
+    this.orchestrator = new Orchestrator({
+      managers: this.options.managers || {}
+    })
+  }
+
+  /**
+   * Create Vue app instance
+   */
+  _createVueApp() {
+    if (!this.options.root) {
+      throw new Error('[Kernel] root component is required')
+    }
+    this.vueApp = createApp(this.options.root)
+  }
+
+  /**
+   * Install all plugins on Vue app
+   */
+  _installPlugins() {
+    const app = this.vueApp
+    const { managers, authAdapter, features, primevue } = this.options
+
+    // Pinia
+    app.use(createPinia())
+
+    // PrimeVue (plugin passed by app to avoid peer dep issues)
+    if (primevue?.plugin) {
+      const pvConfig = {
+        theme: {
+          preset: primevue.theme,
+          options: {
+            darkModeSelector: '.dark-mode',
+            ...primevue.options
+          }
+        }
+      }
+      app.use(primevue.plugin, pvConfig)
+      app.use(ToastService)
+      app.use(ConfirmationService)
+      app.directive('tooltip', Tooltip)
+    }
+
+    // Router
+    app.use(this.router)
+
+    // qdadm plugin
+    app.use(createQdadm({
+      orchestrator: this.orchestrator,
+      managers,
+      authAdapter,
+      router: this.router,
+      toast: app.config.globalProperties.$toast,
+      app: this.options.app,
+      features: {
+        auth: !!authAdapter,
+        poweredBy: true,
+        ...features
+      }
+    }))
+  }
+
+  /**
+   * Get the Vue Router instance
+   * @returns {Router}
+   */
+  getRouter() {
+    return this.router
+  }
+
+  /**
+   * Get the Vue app instance (available after mount)
+   * @returns {App}
+   */
+  getApp() {
+    return this.vueApp
+  }
+
+  /**
+   * Get the Orchestrator instance
+   * @returns {Orchestrator}
+   */
+  getOrchestrator() {
+    return this.orchestrator
+  }
+}

package/src/kernel/index.js

@@ -0,0 +1,7 @@
+/**
+ * Kernel Module
+ *
+ * Simplified bootstrap for qdadm applications.
+ */
+
+export { Kernel } from './Kernel.js'

package/src/module/index.js

@@ -0,0 +1,16 @@
+/**
+ * qdadm - Module system exports
+ */
+
+export {
+  registry,
+  initModules,
+  setSectionOrder,
+  getRoutes,
+  getNavSections,
+  getRouteFamilies,
+  getEntityConfigs,
+  getEntityConfig,
+  isRouteInFamily,
+  resetRegistry
+} from './moduleRegistry'