@quazardous/qdadm 1.19.3

package/src/composables/useOptionsLookup.ts

@@ -0,0 +1,323 @@
+/**
+ * useOptionsLookup - Generic composable for autocomplete/dropdown options
+ *
+ * Fetches options from entity managers or API endpoints for use in any form field.
+ * Two modes:
+ * - **Pure mode** (default for string/number arrays): returns raw values directly.
+ *   Use with MultiSelect :options or AutoComplete :suggestions on string[] fields.
+ * - **Mapped mode** (objects with label/value): returns { label, value } items.
+ *   Use when source items are objects and you need label ≠ value.
+ *
+ * Mapped mode display strategies (displayMode):
+ * - **bracket** (default): suggestions show "Label [value]", decode extracts from brackets.
+ * - **hidden**: suggestions show only "Label", value is resolved via internal lookup.
+ *   If the user types a label not in the list, decode returns the typed string as-is.
+ *
+ * Usage:
+ * ```ts
+ * // Pure strings — suggestions are string[]
+ * const tags = useOptionsLookup({ endpoint: '/api/admin/tags' })
+ *
+ * // Mapped mode with bracket display (default)
+ * const pools = useOptionsLookup({ entity: 'botPools', label: 'name', value: 'id' })
+ * // suggestions = ["Pool Alpha [pool-1]", "Pool Beta [pool-2]"]
+ * // pools.decode("Pool Alpha [pool-1]") → "pool-1"
+ *
+ * // Mapped mode with hidden display — user sees labels only
+ * const pools = useOptionsLookup({
+ *   entity: 'botPools', label: 'name', value: 'id',
+ *   displayMode: 'hidden',
+ * })
+ * // suggestions = ["Pool Alpha", "Pool Beta"]
+ * // pools.decode("Pool Alpha") → "pool-1"
+ * // pools.resolve("pool-1") → "Pool Alpha"
+ *
+ * // Custom encode/decode (overrides displayMode)
+ * const custom = useOptionsLookup({
+ *   entity: 'users', label: 'username', value: 'id',
+ *   encode: (item) => `${item.label} (#${item.value})`,
+ *   decode: (str) => { const m = str.match(/#(.+)\)$/); return m?.[1] ?? str },
+ * })
+ * ```
+ */
+import { ref, onMounted, type Ref } from 'vue'
+import { useOrchestrator } from '../orchestrator/useOrchestrator.js'
+
+export interface OptionsLookupItem {
+  label: string
+  value: unknown
+}
+
+/** Default encode: "Label [value]" */
+function defaultEncode(item: OptionsLookupItem): string {
+  return `${item.label} [${item.value}]`
+}
+
+/** Default decode: extract value from trailing "[value]" */
+function defaultDecode(encoded: string): unknown {
+  const match = encoded.match(/\[([^\]]+)\]\s*$/)
+  return match ? match[1] : encoded
+}
+
+export type OptionsDisplayMode = 'bracket' | 'hidden'
+
+export interface UseOptionsLookupConfig {
+  /** Fetch options from an entity manager (via orchestrator) */
+  entity?: string
+  /** Extract distinct values from a specific field (entity mode only) */
+  field?: string
+  /** Fetch options from a raw API endpoint */
+  endpoint?: string
+  /** When using endpoint: pick a sub-key from the response data */
+  pick?: string
+  /** Extra headers for endpoint fetch (e.g. Authorization) */
+  headers?: Record<string, string> | (() => Record<string, string>)
+  /** Static options (no fetch needed) */
+  static?: unknown[]
+  /** Field to use as display label (default: 'name'). Only for mapped mode. */
+  label?: string
+  /** Field to use as value (default: 'id'). Only for mapped mode. */
+  value?: string
+  /**
+   * How to display mapped values in autocomplete (default: 'bracket').
+   * - 'bracket': "Label [value]" — value visible, decode parses brackets
+   * - 'hidden': "Label" — value hidden, decode uses internal label→value lookup
+   * Ignored when custom encode/decode are provided.
+   */
+  displayMode?: OptionsDisplayMode
+  /** Custom encode function: item → display string (overrides displayMode) */
+  encode?: (item: OptionsLookupItem) => string
+  /** Custom decode function: display string → raw value (overrides displayMode) */
+  decode?: (encoded: string) => unknown
+  /** Post-process mapped options */
+  transform?: (items: OptionsLookupItem[]) => OptionsLookupItem[]
+  /** Auto-load on mount (default: true) */
+  autoLoad?: boolean
+  /** Threshold: use autocomplete UI if options exceed this count */
+  autocompleteThreshold?: number
+}
+
+export interface UseOptionsLookupReturn {
+  /** Mapped options ({ label, value }[]) for complex dropdowns */
+  options: Ref<OptionsLookupItem[]>
+  /** Pure values (string[] or number[]) for simple MultiSelect/AutoComplete */
+  values: Ref<unknown[]>
+  /** Raw items as fetched (before any mapping) */
+  raw: Ref<unknown[]>
+  /** Loading state */
+  loading: Ref<boolean>
+  /** Error message if fetch failed */
+  error: Ref<string | null>
+  /** Filtered suggestions — always string[] (pure values or encoded strings) */
+  suggestions: Ref<string[]>
+  /** Whether autocomplete is recommended (options exceed threshold) */
+  useAutocomplete: Ref<boolean>
+  /** Whether data is pure primitives (strings/numbers) */
+  isPure: Ref<boolean>
+  /** Filter options by query string (for AutoComplete @complete) */
+  search: (query: string) => void
+  /** Manually (re)load options */
+  load: () => Promise<void>
+  /** Decode an encoded display string back to raw value. Identity in pure mode. */
+  decode: (encoded: string) => unknown
+  /** Encode an item { label, value } to display string. */
+  encode: (item: OptionsLookupItem) => string
+  /** Resolve a raw value to its encoded display string. Returns String(val) if not found. */
+  resolve: (rawValue: unknown) => string
+}
+
+export function useOptionsLookup(config: UseOptionsLookupConfig): UseOptionsLookupReturn {
+  const options = ref<OptionsLookupItem[]>([])
+  const values = ref<unknown[]>([])
+  const raw = ref<unknown[]>([])
+  const loading = ref(false)
+  const error = ref<string | null>(null)
+  const suggestions = ref<string[]>([])
+  const useAutocomplete = ref(false)
+  const isPure = ref(false)
+
+  const labelField = config.label ?? 'name'
+  const valueField = config.value ?? 'id'
+  const threshold = config.autocompleteThreshold ?? 50
+  const displayMode = config.displayMode ?? 'bracket'
+
+  // Label→value map for hidden mode decode (rebuilt on processItems)
+  let labelToValue = new Map<string, unknown>()
+
+  // Resolve encode/decode based on displayMode (custom overrides all)
+  const encodeFn = config.encode ?? (
+    displayMode === 'hidden'
+      ? (item: OptionsLookupItem) => item.label
+      : defaultEncode
+  )
+  const decodeFn = config.decode ?? (
+    displayMode === 'hidden'
+      ? (encoded: string) => {
+          // Exact match first, then case-insensitive
+          if (labelToValue.has(encoded)) return labelToValue.get(encoded)
+          const lower = encoded.toLowerCase()
+          for (const [label, value] of labelToValue) {
+            if (label.toLowerCase() === lower) return value
+          }
+          return encoded // Not found → return as-is (manual input)
+        }
+      : defaultDecode
+  )
+
+  // Resolve orchestrator lazily (only if entity mode)
+  let getManager: ((name: string) => { list: (params?: Record<string, unknown>) => Promise<{ items: unknown[] }> }) | null = null
+
+  if (config.entity) {
+    try {
+      const orc = useOrchestrator()
+      // Generic-vs-non-generic: getManager is parameterised by an
+      // EntityRecord type variable that the local alias intentionally
+      // erases. Bridge through `unknown` so strict TS doesn't reject
+      // the cross-shape assignment.
+      getManager = orc.getManager as unknown as typeof getManager
+    } catch {
+      // Orchestrator not available
+    }
+  }
+
+  // Encoded strings cache for mapped mode (rebuilt on processItems)
+  let encodedStrings: string[] = []
+
+  function processItems(items: unknown[]): void {
+    raw.value = items
+
+    // Detect pure mode: all items are primitives (string/number)
+    const allPrimitive = items.length > 0 && items.every(
+      (item) => typeof item === 'string' || typeof item === 'number',
+    )
+    isPure.value = allPrimitive
+
+    if (allPrimitive) {
+      // Pure mode — values are the items themselves
+      values.value = items
+      options.value = items.map((item) => ({ label: String(item), value: item }))
+      encodedStrings = items.map(String)
+    } else {
+      // Mapped mode — extract label/value from objects
+      options.value = items.map((item) => {
+        const obj = item as Record<string, unknown>
+        return {
+          label: String(obj[labelField] ?? obj.label ?? obj.name ?? obj[valueField] ?? item),
+          value: obj[valueField] ?? obj.value ?? obj.id ?? item,
+        }
+      })
+      values.value = options.value.map((opt) => opt.value)
+
+      if (config.transform) options.value = config.transform(options.value)
+
+      // Pre-compute encoded strings for suggestions
+      encodedStrings = options.value.map(encodeFn)
+
+      // Build label→value map for hidden mode decode
+      labelToValue = new Map(options.value.map((opt) => [encodeFn(opt), opt.value]))
+    }
+
+    useAutocomplete.value = items.length > threshold
+
+    // Pre-fill suggestions so dropdown button works on first click
+    suggestions.value = encodedStrings
+  }
+
+  async function load(): Promise<void> {
+    // Static mode — no fetch
+    if (config.static) {
+      processItems(config.static)
+      return
+    }
+
+    loading.value = true
+    error.value = null
+
+    try {
+      let items: unknown[] = []
+
+      if (config.entity && getManager) {
+        const manager = getManager(config.entity)
+        const result = await manager.list({ page_size: 10000 })
+        const rawItems = result.items ?? []
+
+        // If field is specified, extract distinct values from that field
+        if (config.field) {
+          const seen = new Set<unknown>()
+          for (const item of rawItems) {
+            const val = (item as Record<string, unknown>)[config.field]
+            if (val != null && !seen.has(val)) {
+              seen.add(val)
+              items.push(val)
+            }
+          }
+        } else {
+          items = rawItems
+        }
+      } else if (config.endpoint) {
+        const extraHeaders = typeof config.headers === 'function' ? config.headers() : config.headers
+        const response = await fetch(config.endpoint, {
+          credentials: 'include',
+          headers: { 'Accept': 'application/json', ...extraHeaders },
+        })
+        if (!response.ok) throw new Error(`HTTP ${response.status}`)
+        const json = await response.json()
+
+        let data = json.data ?? json
+
+        if (config.pick && typeof data === 'object' && !Array.isArray(data)) {
+          data = (data as Record<string, unknown>)[config.pick]
+        }
+
+        items = Array.isArray(data) ? data : []
+      }
+
+      processItems(items)
+    } catch (err) {
+      error.value = err instanceof Error ? err.message : String(err)
+    } finally {
+      loading.value = false
+    }
+  }
+
+  function search(query: string): void {
+    let result: string[]
+    if (!query) {
+      result = encodedStrings
+    } else {
+      const q = query.toLowerCase()
+      const filtered = encodedStrings.filter(
+        (s) => s.toLowerCase().includes(q),
+      )
+      // When query exactly matches a single option (e.g. dropdown click with
+      // current value), show all options so the user can browse alternatives
+      result = (filtered.length === 1 && filtered[0].toLowerCase() === q)
+        ? encodedStrings
+        : filtered
+    }
+    // Always assign a new array reference so PrimeVue detects the change
+    suggestions.value = [...result]
+  }
+
+  function decode(encoded: string): unknown {
+    if (isPure.value) return encoded
+    return decodeFn(encoded)
+  }
+
+  function encode(item: OptionsLookupItem): string {
+    return encodeFn(item)
+  }
+
+  function resolve(rawValue: unknown): string {
+    const opt = options.value.find((o) => o.value === rawValue || String(o.value) === String(rawValue))
+    if (!opt) return String(rawValue ?? '')
+    if (isPure.value) return opt.label
+    return encodeFn(opt)
+  }
+
+  if (config.autoLoad !== false) {
+    onMounted(() => load())
+  }
+
+  return { options, values, raw, loading, error, suggestions, useAutocomplete, isPure, search, load, decode, encode, resolve }
+}

package/src/composables/usePageTitle.ts

@@ -0,0 +1,84 @@
+/**
+ * usePageTitle - Provide custom page title for PageHeader
+ *
+ * Use this composable in custom pages to set the title displayed in PageHeader.
+ * For standard CRUD pages, useForm handles this automatically.
+ *
+ * Usage:
+ * ```ts
+ * // Simple title
+ * const { setTitle } = usePageTitle('My Custom Page')
+ *
+ * // Decorated title (entityLabel shown prominently, action+entityName as badge)
+ * usePageTitle({
+ *   action: 'View',
+ *   entityName: 'Stats',
+ *   entityLabel: 'Dashboard'
+ * })
+ *
+ * // Reactive updates
+ * const { setTitle } = usePageTitle('Initial')
+ * setTitle('Updated Title')
+ * ```
+ */
+import { ref, provide, watchEffect, isRef, unref, type Ref } from 'vue'
+
+/**
+ * Title parts for decorated title display
+ */
+export interface TitleParts {
+  simple?: string
+  action?: string
+  entityName?: string
+  entityLabel?: string
+}
+
+/**
+ * Title input type - can be string or TitleParts object
+ */
+export type TitleInput = string | TitleParts | null
+
+/**
+ * Return type for usePageTitle
+ */
+export interface UsePageTitleReturn {
+  titleParts: Ref<TitleParts | null>
+  setTitle: (newTitle: TitleInput | Ref<TitleInput>) => void
+}
+
+export function usePageTitle(
+  initialTitle: TitleInput | Ref<TitleInput> = null
+): UsePageTitleReturn {
+  const titleParts = ref<TitleParts | null>(null)
+
+  // Convert string to titleParts format (simple title)
+  function normalize(title: TitleInput): TitleParts | null {
+    if (!title) return null
+    if (typeof title === 'string') {
+      return { simple: title }
+    }
+    return title
+  }
+
+  // Set title (string or { action, entityName, entityLabel })
+  function setTitle(newTitle: TitleInput | Ref<TitleInput>): void {
+    titleParts.value = normalize(unref(newTitle))
+  }
+
+  // Initialize with provided value
+  if (initialTitle !== null) {
+    if (isRef(initialTitle)) {
+      // Reactive: watch for changes
+      watchEffect(() => {
+        setTitle(initialTitle.value)
+      })
+    } else {
+      setTitle(initialTitle)
+    }
+  }
+
+  // Provide to PageHeader via same key as useForm
+  provide('qdadmPageTitleParts', titleParts)
+
+  return { titleParts, setTitle }
+}

package/src/composables/useSSEBridge.ts

@@ -0,0 +1,142 @@
+/**
+ * useSSEBridge - Composable for SSE connection status
+ *
+ * Provides reactive connection status for SSEBridge.
+ * Components use this instead of managing their own EventSource.
+ *
+ * Usage:
+ * ```ts
+ * 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, type Ref } from 'vue'
+import { SSE_SIGNALS } from '../kernel/SSEBridge'
+import type { SignalBus } from '../kernel/SignalBus'
+
+/**
+ * SSE Bridge interface
+ */
+interface SSEBridgeInstance {
+  isConnected: () => boolean
+  isReconnecting: () => boolean
+}
+
+/**
+ * Signal payload with error
+ */
+interface SSEErrorPayload {
+  error: string
+}
+
+/**
+ * Return type for useSSEBridge
+ */
+export interface UseSSEBridgeReturn {
+  /** Connection status */
+  connected: Ref<boolean>
+  /** Reconnection in progress */
+  reconnecting: Ref<boolean>
+  /** Last error message */
+  error: Ref<string | null>
+  /** Subscribe to SSE event (auto-cleanup) */
+  onEvent: (eventName: string, handler: (payload: unknown) => void) => () => void
+  /** Subscribe to all SSE events (wildcard) */
+  onAnyEvent: (handler: (payload: unknown) => void) => () => void
+}
+
+/**
+ * Composable for SSEBridge connection status
+ * @returns SSE bridge state and methods
+ */
+export function useSSEBridge(): UseSSEBridgeReturn {
+  const signals = inject<SignalBus | null>('qdadmSignals', null)
+  const sseBridge = inject<SSEBridgeInstance | null>('qdadmSSEBridge', null)
+
+  const connected = ref(sseBridge?.isConnected() ?? false)
+  const reconnecting = ref(sseBridge?.isReconnecting() ?? false)
+  const error = ref<string | null>(null)
+
+  const unbinders: Array<() => void> = []
+
+  // 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: unknown) => {
+      const errorPayload = payload as SSEErrorPayload
+      error.value = errorPayload.error
+      reconnecting.value = true
+    })
+    unbinders.push(unbindError)
+  }
+
+  /**
+   * Subscribe to a specific SSE event
+   * Automatically cleans up on component unmount.
+   *
+   * @param eventName - SSE event name (without 'sse:' prefix)
+   * @param handler - Event handler (payload) => void
+   * @returns Unbind function
+   */
+  const onEvent = (eventName: string, handler: (payload: unknown) => void): (() => void) => {
+    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 handler - Event handler (payload) => void
+   * @returns Unbind function
+   */
+  const onAnyEvent = (handler: (payload: unknown) => void): (() => void) => {
+    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,
+  }
+}