qdadm 0.28.0 → 0.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qdadm",
-  "version": "0.28.0",
+  "version": "0.30.0",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",
@@ -22,10 +22,13 @@
     ".": "./src/index.js",
     "./composables": "./src/composables/index.js",
     "./components": "./src/components/index.js",
+    "./editors": "./src/editors/index.js",
     "./module": "./src/module/index.js",
     "./utils": "./src/utils/index.js",
     "./styles": "./src/styles/index.scss",
-    "./styles/breakpoints": "./src/styles/_breakpoints.scss"
+    "./styles/breakpoints": "./src/styles/_breakpoints.scss",
+    "./gen": "./src/gen/index.js",
+    "./gen/vite-plugin": "./src/gen/vite-plugin.js"
   },
   "files": [
     "src",
@@ -38,10 +41,17 @@
   "peerDependencies": {
     "pinia": "^2.0.0",
     "primevue": "^4.0.0",
-    "vanilla-jsoneditor": "^0.23.0",
     "vue": "^3.3.0",
     "vue-router": "^4.0.0"
   },
+  "peerDependenciesMeta": {
+    "vanilla-jsoneditor": {
+      "optional": true
+    }
+  },
+  "optionalDependencies": {
+    "vanilla-jsoneditor": "^0.23.0"
+  },
   "keywords": [
     "vue",
     "vue3",

package/src/components/index.js

@@ -32,15 +32,17 @@ export { default as ActionButtons } from './lists/ActionButtons.vue'
 export { default as ActionColumn } from './lists/ActionColumn.vue'
 export { default as FilterBar } from './lists/FilterBar.vue'
 
-// Editors
+// Editors (vanilla-jsoneditor free)
 export { default as KeyValueEditor } from './editors/KeyValueEditor.vue'
 export { default as LanguageEditor } from './editors/LanguageEditor.vue'
 export { default as ScopeEditor } from './editors/ScopeEditor.vue'
-export { default as VanillaJsonEditor } from './editors/VanillaJsonEditor.vue'
 export { default as JsonEditorFoldable } from './editors/JsonEditorFoldable.vue'
-export { default as JsonStructuredField } from './editors/JsonStructuredField.vue'
 export { default as JsonViewer } from './editors/JsonViewer.vue'
 
+// NOTE: VanillaJsonEditor and JsonStructuredField require vanilla-jsoneditor
+// Import from 'qdadm/editors' instead:
+// import { VanillaJsonEditor, JsonStructuredField } from 'qdadm/editors'
+
 // Dialogs
 export { default as SimpleDialog } from './dialogs/SimpleDialog.vue'
 export { default as MultiStepDialog } from './dialogs/MultiStepDialog.vue'

package/src/composables/index.js

@@ -20,5 +20,5 @@ export { useSignals } from './useSignals'
 export { useZoneRegistry } from './useZoneRegistry'
 export { useHooks } from './useHooks'
 export { useLayoutResolver, createLayoutComponents, layoutMeta, LAYOUT_TYPES } from './useLayoutResolver'
-export { useSSE } from './useSSE'
+export { useSSEBridge } from './useSSEBridge'
 export { useDeferred, useDeferredValue, DEFERRED_INJECTION_KEY } from './useDeferred'

package/src/composables/useSSEBridge.js

@@ -0,0 +1,118 @@
+/**
+ * useSSEBridge - Composable for SSE connection status
+ *
+ * Provides reactive connection status for SSEBridge.
+ * Components use this instead of managing their own EventSource.
+ *
+ * Usage:
+ * ```js
+ * const { connected, reconnecting, error, onEvent } = useSSEBridge()
+ *
+ * // Reactive connection status
+ * watchEffect(() => {
+ *   if (connected.value) {
+ *     console.log('SSE connected')
+ *   }
+ * })
+ *
+ * // Subscribe to specific event (auto-cleanup on unmount)
+ * onEvent('task:completed', (payload) => {
+ *   console.log('Task completed:', payload.data)
+ * })
+ * ```
+ */
+
+import { ref, inject, onUnmounted, onMounted } from 'vue'
+import { SSE_SIGNALS } from '../kernel/SSEBridge.js'
+
+/**
+ * @typedef {object} UseSSEBridgeReturn
+ * @property {import('vue').Ref<boolean>} connected - Connection status
+ * @property {import('vue').Ref<boolean>} reconnecting - Reconnection in progress
+ * @property {import('vue').Ref<string|null>} error - Last error message
+ * @property {function} onEvent - Subscribe to SSE event (auto-cleanup)
+ * @property {function} onAnyEvent - Subscribe to all SSE events (wildcard)
+ */
+
+/**
+ * Composable for SSEBridge connection status
+ * @returns {UseSSEBridgeReturn}
+ */
+export function useSSEBridge() {
+  const signals = inject('qdadmSignals')
+  const sseBridge = inject('qdadmSSEBridge', null)
+
+  const connected = ref(sseBridge?.isConnected() ?? false)
+  const reconnecting = ref(sseBridge?.isReconnecting() ?? false)
+  const error = ref(null)
+
+  const unbinders = []
+
+  // Track connection status via signals
+  if (signals) {
+    const unbindConnected = signals.on(SSE_SIGNALS.CONNECTED, () => {
+      connected.value = true
+      reconnecting.value = false
+      error.value = null
+    })
+    unbinders.push(unbindConnected)
+
+    const unbindDisconnected = signals.on(SSE_SIGNALS.DISCONNECTED, () => {
+      connected.value = false
+    })
+    unbinders.push(unbindDisconnected)
+
+    const unbindError = signals.on(SSE_SIGNALS.ERROR, (payload) => {
+      error.value = payload.error
+      reconnecting.value = true
+    })
+    unbinders.push(unbindError)
+  }
+
+  /**
+   * Subscribe to a specific SSE event
+   * Automatically cleans up on component unmount.
+   *
+   * @param {string} eventName - SSE event name (without 'sse:' prefix)
+   * @param {function} handler - Event handler (payload) => void
+   * @returns {function} Unbind function
+   */
+  const onEvent = (eventName, handler) => {
+    if (!signals) return () => {}
+
+    const signal = `sse:${eventName}`
+    const unbind = signals.on(signal, handler)
+    unbinders.push(unbind)
+
+    return unbind
+  }
+
+  /**
+   * Subscribe to all SSE events (wildcard)
+   * Automatically cleans up on component unmount.
+   *
+   * @param {function} handler - Event handler (payload) => void
+   * @returns {function} Unbind function
+   */
+  const onAnyEvent = (handler) => {
+    if (!signals) return () => {}
+
+    const unbind = signals.on('sse:*', handler)
+    unbinders.push(unbind)
+
+    return unbind
+  }
+
+  // Cleanup on unmount
+  onUnmounted(() => {
+    unbinders.forEach(unbind => unbind())
+  })
+
+  return {
+    connected,
+    reconnecting,
+    error,
+    onEvent,
+    onAnyEvent
+  }
+}

package/src/editors/index.js

@@ -0,0 +1,12 @@
+/**
+ * qdadm/editors - Optional editors that require vanilla-jsoneditor
+ *
+ * Import from 'qdadm/editors' only if you need VanillaJsonEditor.
+ * This keeps vanilla-jsoneditor out of the main bundle.
+ *
+ * Usage:
+ * import { VanillaJsonEditor, JsonStructuredField } from 'qdadm/editors'
+ */
+
+export { default as VanillaJsonEditor } from '../components/editors/VanillaJsonEditor.vue'
+export { default as JsonStructuredField } from '../components/editors/JsonStructuredField.vue'

package/src/gen/FieldMapper.js

@@ -0,0 +1,116 @@
+/**
+ * Field Type Mapper
+ *
+ * Maps JSON Schema types and formats to UnifiedFieldSchema types.
+ * Extracted from Skybot and Faketual to eliminate duplication.
+ *
+ * Mapping priority:
+ * 1. Enum detection (schema.enum present -> 'select')
+ * 2. Custom mappings (user-provided)
+ * 3. Format-specific mappings (e.g., string + format:email -> email)
+ * 4. Base type mappings (e.g., string -> text)
+ *
+ * @module gen/FieldMapper
+ */
+
+/**
+ * Base type mappings: JSON Schema type -> UnifiedFieldSchema type
+ *
+ * @type {Readonly<Record<string, import('./schema.js').UnifiedFieldType>>}
+ */
+export const BASE_TYPE_MAPPINGS = Object.freeze({
+  string: 'text',
+  integer: 'number',
+  number: 'number',
+  boolean: 'boolean',
+  array: 'array',
+  object: 'object'
+})
+
+/**
+ * Format-specific mappings: JSON Schema format -> UnifiedFieldSchema type
+ *
+ * These take precedence over base type mappings when a format is specified.
+ *
+ * @type {Readonly<Record<string, import('./schema.js').UnifiedFieldType>>}
+ */
+export const FORMAT_MAPPINGS = Object.freeze({
+  email: 'email',
+  'date-time': 'datetime',
+  date: 'date',
+  uri: 'url',
+  url: 'url',
+  uuid: 'uuid',
+  password: 'text'
+})
+
+/**
+ * Custom mappings override structure
+ *
+ * @typedef {object} CustomMappings
+ * @property {Record<string, string>} [types] - Custom type mappings { jsonSchemaType: unifiedType }
+ * @property {Record<string, string>} [formats] - Custom format mappings { jsonSchemaFormat: unifiedType }
+ */
+
+/**
+ * Minimal JSON Schema property definition for type detection
+ *
+ * @typedef {object} SchemaProperty
+ * @property {string} [type] - JSON Schema type (string, integer, number, boolean, array, object)
+ * @property {string} [format] - JSON Schema format (email, date-time, uuid, etc.)
+ * @property {Array<*>} [enum] - Enumeration values
+ */
+
+/**
+ * Get the UnifiedFieldSchema type for a JSON Schema property
+ *
+ * @param {SchemaProperty} schema - JSON Schema property definition
+ * @param {CustomMappings} [customMappings] - Optional custom type/format mappings
+ * @returns {import('./schema.js').UnifiedFieldType | 'select'} - Unified field type
+ *
+ * @example
+ * // Basic type mapping
+ * getDefaultType({ type: 'string' })           // 'text'
+ * getDefaultType({ type: 'integer' })          // 'number'
+ *
+ * @example
+ * // Format takes precedence
+ * getDefaultType({ type: 'string', format: 'email' })  // 'email'
+ * getDefaultType({ type: 'string', format: 'uuid' })   // 'uuid'
+ *
+ * @example
+ * // Enum detection
+ * getDefaultType({ type: 'string', enum: ['a', 'b'] }) // 'select'
+ *
+ * @example
+ * // Custom mappings
+ * getDefaultType({ type: 'string', format: 'phone' }, {
+ *   formats: { phone: 'text' }
+ * })  // 'text'
+ */
+export function getDefaultType(schema, customMappings = {}) {
+  const { type, format } = schema || {}
+
+  // Check for enum pattern first (returns 'select')
+  if (Array.isArray(schema?.enum) && schema.enum.length > 0) {
+    return 'select'
+  }
+
+  // Check custom format mapping
+  if (format && customMappings.formats?.[format]) {
+    return customMappings.formats[format]
+  }
+
+  // Check default format mapping
+  if (format && FORMAT_MAPPINGS[format]) {
+    return FORMAT_MAPPINGS[format]
+  }
+
+  // Check custom type mapping
+  if (type && customMappings.types?.[type]) {
+    return customMappings.types[type]
+  }
+
+  // Fall back to base type mapping, default to 'text'
+  return BASE_TYPE_MAPPINGS[type] || 'text'
+}

package/src/gen/StorageProfileFactory.js

@@ -0,0 +1,109 @@
+/**
+ * Storage Profile Factory Pattern
+ *
+ * A storage profile factory is a function that creates storage instances for a given endpoint.
+ * This pattern enables DRY backend configuration by centralizing storage creation logic
+ * (API client, base URL, headers, error handling) in one place.
+ *
+ * Instead of configuring each entity's storage individually, you define a profile factory
+ * once and pass it to createManagers(), which calls it with each entity's endpoint.
+ *
+ * @module gen/StorageProfileFactory
+ */
+
+/**
+ * Storage Profile Factory Options
+ *
+ * Per-entity options passed when creating storage from a profile factory.
+ * Allows overriding profile defaults for specific entities.
+ *
+ * @typedef {object} StorageProfileOptions
+ * @property {string} [entity] - Entity name (e.g., 'users', 'posts')
+ * @property {object} [client] - Override the profile's HTTP client for this entity
+ * @property {object} [headers] - Additional headers for this entity
+ * @property {boolean} [readOnly] - Force read-only mode (no create/update/delete)
+ * @property {Record<string, *>} [extensions] - Custom per-entity options
+ */
+
+/**
+ * Storage Profile Factory
+ *
+ * A function that creates storage instances for a given endpoint.
+ * The factory encapsulates common storage configuration (API client, auth, base URL)
+ * and creates properly-configured storage adapters for each entity.
+ *
+ * @callback StorageProfileFactory
+ * @param {string} endpoint - Entity endpoint path (e.g., '/users', '/api/v1/posts')
+ * @param {StorageProfileOptions} [options] - Per-entity options to override profile defaults
+ * @returns {import('../entity/storage/IStorage.js').IStorage} Storage instance
+ *
+ * @example Basic factory using ApiStorage
+ * import axios from 'axios'
+ * import { ApiStorage } from 'qdadm'
+ *
+ * // Define profile factory with shared configuration
+ * const apiProfile = (endpoint, options = {}) => {
+ *   return new ApiStorage({
+ *     endpoint,
+ *     client: axios.create({
+ *       baseURL: 'https://api.example.com',
+ *       headers: { 'Authorization': `Bearer ${getToken()}` }
+ *     }),
+ *     ...options
+ *   })
+ * }
+ *
+ * // Use with createManagers (T00317)
+ * const managers = createManagers(schemas, {
+ *   storageProfile: apiProfile
+ * })
+ *
+ * @example Factory with dynamic client resolution
+ * // For Vue/inject pattern - client resolved at call time
+ * const lazyApiProfile = (endpoint, options = {}) => {
+ *   return new ApiStorage({
+ *     endpoint,
+ *     getClient: () => inject('apiClient'),
+ *     ...options
+ *   })
+ * }
+ *
+ * @example Factory for local development
+ * import { MemoryStorage } from 'qdadm'
+ *
+ * const memoryProfile = (endpoint, options = {}) => {
+ *   const entity = options.entity || endpoint.replace(/^\//, '')
+ *   return new MemoryStorage({
+ *     initialData: mockData[entity] || []
+ *   })
+ * }
+ *
+ * @example Factory with per-entity overrides
+ * const hybridProfile = (endpoint, options = {}) => {
+ *   // Some entities use SDK, others use REST
+ *   if (options.useSdk) {
+ *     return new SdkStorage({
+ *       sdk: options.sdk,
+ *       collection: options.entity
+ *     })
+ *   }
+ *   return new ApiStorage({
+ *     endpoint,
+ *     client: defaultClient
+ *   })
+ * }
+ *
+ * @example Factory with environment-based switching
+ * const envAwareProfile = (endpoint, options = {}) => {
+ *   if (import.meta.env.MODE === 'development') {
+ *     return new MockApiStorage({ endpoint })
+ *   }
+ *   return new ApiStorage({
+ *     endpoint,
+ *     client: productionClient
+ *   })
+ * }
+ */
+
+// Type-only module - no runtime exports
+// Types are available via JSDoc when importing this module

package/src/gen/connectors/BaseConnector.js

@@ -0,0 +1,142 @@
+/**
+ * Base Connector Interface
+ *
+ * Abstract base class for schema connectors. Connectors parse various sources
+ * (OpenAPI specs, manual definitions, etc.) into UnifiedEntitySchema format.
+ *
+ * Subclasses must implement the `parse(source)` method with source-specific logic.
+ *
+ * @module gen/connectors/BaseConnector
+ */
+
+/**
+ * Connector options for customizing parsing behavior
+ *
+ * @typedef {object} ConnectorOptions
+ * @property {string} [name] - Connector instance name for debugging
+ * @property {boolean} [strict] - Throw on validation errors instead of warning (default: false)
+ * @property {Record<string, *>} [extensions] - Custom extension data passed to output schemas
+ */
+
+/**
+ * Parse result with parsed schemas and any encountered issues
+ *
+ * @typedef {object} ParseResult
+ * @property {import('../schema.js').UnifiedEntitySchema[]} schemas - Parsed entity schemas
+ * @property {ParseWarning[]} warnings - Non-fatal issues encountered during parsing
+ */
+
+/**
+ * Warning encountered during parsing
+ *
+ * @typedef {object} ParseWarning
+ * @property {string} path - Location in source where issue occurred
+ * @property {string} message - Description of the issue
+ * @property {string} [code] - Warning code for programmatic handling
+ */
+
+/**
+ * Base connector class for parsing schema sources into UnifiedEntitySchema format.
+ *
+ * @abstract
+ * @example
+ * // Extending BaseConnector
+ * class ManualConnector extends BaseConnector {
+ *   parse(source) {
+ *     // Parse inline definitions
+ *     return source.entities.map(e => this.transformEntity(e))
+ *   }
+ * }
+ *
+ * @example
+ * // Using a connector
+ * const connector = new ManualConnector({ strict: true })
+ * const schemas = connector.parse(manualDefinitions)
+ */
+export class BaseConnector {
+  /**
+   * Create a new connector instance
+   *
+   * @param {ConnectorOptions} [options={}] - Connector configuration options
+   */
+  constructor(options = {}) {
+    if (new.target === BaseConnector) {
+      throw new Error('BaseConnector is abstract and cannot be instantiated directly')
+    }
+
+    /** @type {string} */
+    this.name = options.name || this.constructor.name
+
+    /** @type {boolean} */
+    this.strict = options.strict ?? false
+
+    /** @type {Record<string, *>} */
+    this.extensions = options.extensions || {}
+  }
+
+  /**
+   * Parse a schema source into UnifiedEntitySchema format.
+   *
+   * This method must be implemented by subclasses to handle source-specific
+   * parsing logic. The source parameter format depends on the connector type:
+   * - ManualConnector: Object with entity/field definitions
+   * - OpenAPIConnector: OpenAPI 3.x specification object
+   *
+   * @abstract
+   * @param {*} source - Source data to parse (format depends on connector type)
+   * @returns {import('../schema.js').UnifiedEntitySchema[]} - Parsed entity schemas
+   * @throws {Error} - If parsing fails (in strict mode) or source is invalid
+   *
+   * @example
+   * // ManualConnector source format
+   * connector.parse({
+   *   entities: [
+   *     { name: 'users', endpoint: '/api/users', fields: { ... } }
+   *   ]
+   * })
+   *
+   * @example
+   * // OpenAPIConnector source format
+   * connector.parse({
+   *   openapi: '3.0.0',
+   *   paths: { '/api/users': { ... } },
+   *   components: { schemas: { ... } }
+   * })
+   */
+  parse(source) {
+    throw new Error(`${this.name}.parse() must be implemented by subclass`)
+  }
+
+  /**
+   * Parse with detailed result including warnings
+   *
+   * Alternative to `parse()` that returns warnings along with schemas.
+   * Useful when you want to handle non-fatal issues without strict mode.
+   *
+   * Default implementation wraps `parse()` with empty warnings array.
+   * Subclasses can override for more detailed reporting.
+   *
+   * @param {*} source - Source data to parse
+   * @returns {ParseResult} - Schemas and any warnings encountered
+   */
+  parseWithWarnings(source) {
+    return {
+      schemas: this.parse(source),
+      warnings: []
+    }
+  }
+
+  /**
+   * Validate connector is properly configured before parsing
+   *
+   * Override in subclasses to add custom validation.
+   *
+   * @returns {boolean} - True if connector is valid
+   * @throws {Error} - If connector configuration is invalid
+   */
+  validate() {
+    return true
+  }
+}
+
+export default BaseConnector