@quazardous/qdadm 1.19.3

package/src/composables/useInfoBanner.ts

@@ -0,0 +1,217 @@
+/**
+ * useInfoBanner - Programmatic banner management
+ *
+ * Manages persistent info banners that appear at the top of page content.
+ * Unlike toasts, banners stay visible until explicitly dismissed.
+ *
+ * @example
+ * // In a component
+ * const { showBanner, hideBanner, clearBanners } = useInfoBanner()
+ *
+ * // Show a warning banner
+ * showBanner({
+ *   id: 'unsaved',
+ *   severity: 'warn',
+ *   message: 'You have unsaved changes',
+ *   closable: true
+ * })
+ *
+ * // Hide a specific banner
+ * hideBanner('unsaved')
+ *
+ * // Clear all banners
+ * clearBanners()
+ *
+ * @example
+ * // With custom icon
+ * showBanner({
+ *   id: 'offline',
+ *   severity: 'error',
+ *   icon: 'pi-wifi',
+ *   message: 'You are offline. Changes will be saved when connection is restored.'
+ * })
+ *
+ * @example
+ * // In layout - get banners to render
+ * const { banners } = useInfoBanner()
+ *
+ * <InfoBanner
+ *   v-for="banner in banners"
+ *   :key="banner.id"
+ *   :severity="banner.severity"
+ *   :icon="banner.icon"
+ *   :closable="banner.closable"
+ *   @close="hideBanner(banner.id)"
+ * >
+ *   {{ banner.message }}
+ * </InfoBanner>
+ */
+import { inject, provide, reactive, computed, type ComputedRef, type InjectionKey } from 'vue'
+
+const BANNER_KEY: InjectionKey<BannerStore> = Symbol('qdadm-banners')
+
+/**
+ * Banner severity types
+ */
+export type BannerSeverity = 'info' | 'success' | 'warn' | 'error'
+
+/**
+ * Banner configuration options
+ */
+export interface BannerOptions {
+  /** Unique identifier (replaces existing with same id) */
+  id?: string
+  /** Banner severity: info, success, warn, error */
+  severity?: BannerSeverity
+  /** Banner message (can include HTML) */
+  message?: string
+  /** Custom icon or false to hide */
+  icon?: string | boolean
+  /** Allow user to dismiss (default: true) */
+  closable?: boolean
+  /** Higher priority banners appear first */
+  priority?: number
+}
+
+/**
+ * Internal banner state
+ */
+export interface Banner {
+  id: string
+  severity: BannerSeverity
+  message: string
+  icon?: string | boolean
+  closable: boolean
+  priority: number
+  createdAt: number
+}
+
+/**
+ * Banner store state
+ */
+interface BannerState {
+  banners: Banner[]
+}
+
+/**
+ * Banner store interface
+ */
+export interface BannerStore {
+  banners: ComputedRef<Banner[]>
+  showBanner: (options: BannerOptions) => string
+  hideBanner: (id: string) => void
+  clearBanners: () => void
+  hasBanner: (id: string) => boolean
+}
+
+/**
+ * Create the banner store (call once in app root)
+ */
+export function createBannerStore(): BannerStore {
+  const state = reactive<BannerState>({
+    banners: [],
+  })
+
+  /**
+   * Show a banner
+   * @param options - Banner options
+   */
+  function showBanner(options: BannerOptions): string {
+    const banner: Banner = {
+      id: options.id || `banner-${Date.now()}`,
+      severity: options.severity || 'info',
+      message: options.message || '',
+      icon: options.icon,
+      closable: options.closable !== false,
+      priority: options.priority || 0,
+      createdAt: Date.now(),
+    }
+
+    // Remove existing banner with same id
+    const existingIndex = state.banners.findIndex((b) => b.id === banner.id)
+    if (existingIndex !== -1) {
+      state.banners.splice(existingIndex, 1)
+    }
+
+    // Insert by priority (higher first)
+    const insertIndex = state.banners.findIndex((b) => b.priority < banner.priority)
+    if (insertIndex === -1) {
+      state.banners.push(banner)
+    } else {
+      state.banners.splice(insertIndex, 0, banner)
+    }
+
+    return banner.id
+  }
+
+  /**
+   * Hide a specific banner
+   * @param id - Banner id to remove
+   */
+  function hideBanner(id: string): void {
+    const index = state.banners.findIndex((b) => b.id === id)
+    if (index !== -1) {
+      state.banners.splice(index, 1)
+    }
+  }
+
+  /**
+   * Clear all banners
+   */
+  function clearBanners(): void {
+    state.banners.length = 0
+  }
+
+  /**
+   * Check if a banner exists
+   * @param id - Banner id
+   * @returns True if banner exists
+   */
+  function hasBanner(id: string): boolean {
+    return state.banners.some((b) => b.id === id)
+  }
+
+  const banners = computed(() => state.banners)
+
+  return {
+    banners,
+    showBanner,
+    hideBanner,
+    clearBanners,
+    hasBanner,
+  }
+}
+
+/**
+ * Provide the banner store to descendant components
+ * Call this in your app root or layout component
+ */
+export function provideBannerStore(): BannerStore {
+  const store = createBannerStore()
+  provide(BANNER_KEY, store)
+  return store
+}
+
+/**
+ * Use the banner system in a component
+ * @returns Banner API
+ */
+export function useInfoBanner(): BannerStore {
+  const store = inject(BANNER_KEY)
+
+  if (!store) {
+    console.warn(
+      '[qdadm] useInfoBanner: banner store not provided. Call provideBannerStore() in app root.'
+    )
+    // Return a no-op store to prevent crashes
+    return {
+      banners: computed(() => []),
+      showBanner: () => '',
+      hideBanner: () => {},
+      clearBanners: () => {},
+      hasBanner: () => false,
+    }
+  }
+
+  return store
+}

package/src/composables/useJsonSyntax.ts

@@ -0,0 +1,122 @@
+/**
+ * useJsonSyntax - Shared JSON syntax highlighting utilities
+ *
+ * Provides consistent JSON formatting and syntax highlighting
+ * across JsonEditor, JsonViewer, and JsonEditorFoldable components.
+ */
+
+/**
+ * JSON value type enumeration
+ */
+export type JsonValueType = 'string' | 'number' | 'boolean' | 'null' | 'array' | 'object'
+
+/**
+ * Result of safe JSON parsing
+ */
+export interface SafeJsonParseResult<T = unknown> {
+  value: T | null
+  error: string | null
+}
+
+/**
+ * Apply syntax highlighting to JSON string
+ * @param jsonText - Raw JSON text
+ * @returns HTML with syntax highlighting spans
+ */
+export function highlightJson(jsonText: string): string {
+  if (!jsonText) {
+    return ''
+  }
+
+  return (
+    jsonText
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      // Strings (values only - after colon or in arrays)
+      .replace(/("(?:[^"\\]|\\.)*")(?=\s*[,\]}]|\s*$)/gm, '<span class="json-string">$1</span>')
+      // Keys (before colon)
+      .replace(/("(?:[^"\\]|\\.)*")(\s*:)/g, '<span class="json-key">$1</span>$2')
+      // Numbers
+      .replace(/\b(-?\d+\.?\d*)\b/g, '<span class="json-number">$1</span>')
+      // Booleans
+      .replace(/\b(true|false)\b/g, '<span class="json-boolean">$1</span>')
+      // Null
+      .replace(/\bnull\b/g, '<span class="json-null">null</span>')
+  )
+}
+
+/**
+ * Get the type of a JSON value for display
+ * @param value - The value to check
+ * @returns Type name: 'string', 'number', 'boolean', 'null', 'array', 'object'
+ */
+export function getJsonValueType(value: unknown): JsonValueType {
+  if (value === null) return 'null'
+  if (Array.isArray(value)) return 'array'
+  return typeof value as JsonValueType
+}
+
+/**
+ * Get a short preview of a JSON value
+ * @param value - The value to preview
+ * @param maxLength - Maximum length for string previews
+ * @returns Short preview text
+ */
+export function getJsonPreview(value: unknown, maxLength = 50): string {
+  const type = getJsonValueType(value)
+
+  switch (type) {
+    case 'string': {
+      const strValue = value as string
+      const preview = strValue.substring(0, maxLength)
+      return preview + (strValue.length > maxLength ? '...' : '')
+    }
+    case 'array': {
+      const arrValue = value as unknown[]
+      return `[${arrValue.length} item${arrValue.length !== 1 ? 's' : ''}]`
+    }
+    case 'object': {
+      const objValue = value as Record<string, unknown>
+      const keyCount = Object.keys(objValue).length
+      return `{${keyCount} key${keyCount !== 1 ? 's' : ''}}`
+    }
+    case 'null':
+      return 'null'
+    case 'boolean':
+      return String(value)
+    case 'number':
+      return String(value)
+    default:
+      return String(value)
+  }
+}
+
+/**
+ * Safely parse JSON with error handling
+ * @param text - JSON text to parse
+ * @returns Parse result with value and error
+ */
+export function safeJsonParse<T = unknown>(text: string): SafeJsonParseResult<T> {
+  if (!text || !text.trim()) {
+    return { value: null, error: null }
+  }
+  try {
+    return { value: JSON.parse(text) as T, error: null }
+  } catch (e) {
+    return { value: null, error: (e as Error).message }
+  }
+}
+
+/**
+ * CSS class names for JSON syntax highlighting
+ * Import these in your component's style section
+ */
+export const JSON_SYNTAX_CLASSES = `
+.json-key { color: #881391; }
+.json-string { color: #1a1aa6; }
+.json-number { color: #1c00cf; }
+.json-boolean { color: #0d22aa; font-weight: 500; }
+.json-null { color: #808080; font-style: italic; }
+.json-placeholder { color: var(--p-surface-400); }
+`

package/src/composables/useLayoutResolver.ts

@@ -0,0 +1,329 @@
+/**
+ * useLayoutResolver - Automatic layout resolution for entity pages
+ *
+ * Resolves the appropriate layout component based on:
+ * 1. Route meta: `{ meta: { layout: 'list' } }` (highest priority)
+ * 2. Page name convention: `*ListPage` -> ListLayout, `*EditPage` -> FormLayout
+ * 3. Explicit prop: `layout="list"` passed to component
+ *
+ * Layout types:
+ * - 'list' -> ListLayout (entity list pages)
+ * - 'form' -> FormLayout (create/edit pages)
+ * - 'dashboard' -> DashboardLayout (dashboard pages)
+ * - 'base' -> BaseLayout (generic pages)
+ *
+ * Usage:
+ * ```ts
+ * const { layoutComponent, layoutType, resolveLayout } = useLayoutResolver()
+ *
+ * // In template:
+ * <component :is="layoutComponent">
+ *   <template #main>...</template>
+ * </component>
+ * ```
+ *
+ * Or with explicit layout prop:
+ * ```ts
+ * const { layoutComponent } = useLayoutResolver({ layout: 'list' })
+ * ```
+ */
+import { computed, inject, getCurrentInstance, type ComputedRef, type Component } from 'vue'
+import { useRoute } from 'vue-router'
+
+// Layout type constants
+export const LAYOUT_TYPES = {
+  LIST: 'list',
+  FORM: 'form',
+  DASHBOARD: 'dashboard',
+  BASE: 'base',
+} as const
+
+export type LayoutType = (typeof LAYOUT_TYPES)[keyof typeof LAYOUT_TYPES]
+
+/**
+ * Layout components map
+ */
+export interface LayoutComponentsMap {
+  list?: Component | null
+  form?: Component | null
+  dashboard?: Component | null
+  base?: Component | null
+  [key: string]: Component | null | undefined
+}
+
+/**
+ * Page name pattern for layout detection
+ */
+interface PageNamePattern {
+  pattern: RegExp
+  layout: LayoutType
+}
+
+// Page name patterns for auto-detection
+const PAGE_NAME_PATTERNS: PageNamePattern[] = [
+  { pattern: /List(Page)?$/i, layout: LAYOUT_TYPES.LIST },
+  { pattern: /(Edit|Create|Form)(Page)?$/i, layout: LAYOUT_TYPES.FORM },
+  { pattern: /Dashboard(Page)?$/i, layout: LAYOUT_TYPES.DASHBOARD },
+]
+
+// Route name patterns for auto-detection
+const ROUTE_NAME_PATTERNS: PageNamePattern[] = [
+  { pattern: /-list$/i, layout: LAYOUT_TYPES.LIST },
+  { pattern: /-(edit|create)$/i, layout: LAYOUT_TYPES.FORM },
+  { pattern: /-dashboard$/i, layout: LAYOUT_TYPES.DASHBOARD },
+  // Common patterns without suffix
+  { pattern: /^dashboard$/i, layout: LAYOUT_TYPES.DASHBOARD },
+]
+
+/**
+ * Resolve layout type from component name
+ * @param componentName - Vue component name
+ * @returns Layout type or null
+ */
+function resolveFromComponentName(componentName: string | null | undefined): LayoutType | null {
+  if (!componentName) return null
+
+  for (const { pattern, layout } of PAGE_NAME_PATTERNS) {
+    if (pattern.test(componentName)) {
+      return layout
+    }
+  }
+  return null
+}
+
+/**
+ * Resolve layout type from route name
+ * @param routeName - Route name
+ * @returns Layout type or null
+ */
+function resolveFromRouteName(routeName: string | null | undefined): LayoutType | null {
+  if (!routeName) return null
+
+  for (const { pattern, layout } of ROUTE_NAME_PATTERNS) {
+    if (pattern.test(routeName)) {
+      return layout
+    }
+  }
+  return null
+}
+
+/**
+ * Options for useLayoutResolver
+ */
+export interface UseLayoutResolverOptions {
+  /** Explicit layout type override */
+  layout?: LayoutType
+  /** Default layout if none detected (default: 'base') */
+  default?: LayoutType
+}
+
+/**
+ * Resolution context for resolveLayout
+ */
+export interface LayoutResolutionContext {
+  routeMeta?: { layout?: LayoutType }
+  componentName?: string
+  routeName?: string
+  explicit?: LayoutType
+}
+
+/**
+ * Return type for useLayoutResolver
+ */
+export interface UseLayoutResolverReturn {
+  /** Current resolved layout type */
+  layoutType: ComputedRef<LayoutType>
+  /** Layout component for current type (if injected) */
+  layoutComponent: ComputedRef<Component | null>
+  /** Check if specific layout type is active */
+  isLayout: (type: LayoutType) => boolean
+  /** Manually resolve layout for given context */
+  resolveLayout: (context?: LayoutResolutionContext) => LayoutType
+  /** Layout type constants */
+  LAYOUT_TYPES: typeof LAYOUT_TYPES
+}
+
+/**
+ * useLayoutResolver composable
+ *
+ * @param options - Configuration options
+ * @returns Layout resolution utilities
+ */
+export function useLayoutResolver(options: UseLayoutResolverOptions = {}): UseLayoutResolverReturn {
+  const route = useRoute()
+  const instance = getCurrentInstance()
+
+  // Get layout components from injection (provided by Kernel)
+  const layoutComponents = inject<LayoutComponentsMap | null>('qdadmLayoutComponents', null)
+
+  /**
+   * Resolve the layout type based on priority:
+   * 1. Explicit option.layout
+   * 2. Route meta.layout
+   * 3. Component name pattern
+   * 4. Route name pattern
+   * 5. Default
+   */
+  const layoutType = computed((): LayoutType => {
+    // Priority 1: Explicit layout prop/option
+    if (options.layout) {
+      return options.layout
+    }
+
+    // Priority 2: Route meta.layout
+    if (route.meta?.layout) {
+      return route.meta.layout as LayoutType
+    }
+
+    // Priority 3: Component name pattern
+    const componentName =
+      (instance?.type as { name?: string; __name?: string })?.name ||
+      (instance?.type as { name?: string; __name?: string })?.__name
+    const fromComponentName = resolveFromComponentName(componentName)
+    if (fromComponentName) {
+      return fromComponentName
+    }
+
+    // Priority 4: Route name pattern
+    const fromRouteName = resolveFromRouteName(route.name as string | undefined)
+    if (fromRouteName) {
+      return fromRouteName
+    }
+
+    // Priority 5: Default
+    return options.default || LAYOUT_TYPES.BASE
+  })
+
+  /**
+   * Get the layout component for the resolved type
+   */
+  const layoutComponent = computed((): Component | null => {
+    if (!layoutComponents) {
+      // No components injected, return null (caller handles fallback)
+      return null
+    }
+
+    const type = layoutType.value
+    return layoutComponents[type] || layoutComponents.base || null
+  })
+
+  /**
+   * Check if a specific layout type is active
+   * @param type - Layout type to check
+   * @returns True if layout type matches
+   */
+  function isLayout(type: LayoutType): boolean {
+    return layoutType.value === type
+  }
+
+  /**
+   * Manually resolve layout for a given context
+   * Useful for programmatic layout determination
+   *
+   * @param context - Resolution context
+   * @returns Resolved layout type
+   */
+  function resolveLayout(context: LayoutResolutionContext = {}): LayoutType {
+    // Priority 1: Explicit
+    if (context.explicit) {
+      return context.explicit
+    }
+
+    // Priority 2: Route meta
+    if (context.routeMeta?.layout) {
+      return context.routeMeta.layout
+    }
+
+    // Priority 3: Component name
+    const fromComponent = resolveFromComponentName(context.componentName)
+    if (fromComponent) {
+      return fromComponent
+    }
+
+    // Priority 4: Route name
+    const fromRoute = resolveFromRouteName(context.routeName)
+    if (fromRoute) {
+      return fromRoute
+    }
+
+    // Default
+    return options.default || LAYOUT_TYPES.BASE
+  }
+
+  return {
+    layoutType,
+    layoutComponent,
+    isLayout,
+    resolveLayout,
+    LAYOUT_TYPES,
+  }
+}
+
+/**
+ * Layout components input for createLayoutComponents
+ */
+export interface LayoutComponentsInput {
+  list?: Component
+  form?: Component
+  dashboard?: Component
+  base?: Component
+  ListLayout?: Component
+  FormLayout?: Component
+  DashboardLayout?: Component
+  BaseLayout?: Component
+}
+
+/**
+ * Create layout components map for Kernel injection
+ *
+ * @param components - Layout component imports
+ * @returns Layout components map
+ *
+ * @example
+ * ```ts
+ * import ListLayout from './components/layout/ListLayout.vue'
+ * import FormLayout from './components/layout/FormLayout.vue'
+ *
+ * const layouts = createLayoutComponents({
+ *   list: ListLayout,
+ *   form: FormLayout
+ * })
+ * ```
+ */
+export function createLayoutComponents(components: LayoutComponentsInput = {}): LayoutComponentsMap {
+  return {
+    [LAYOUT_TYPES.LIST]: components.list || components.ListLayout || null,
+    [LAYOUT_TYPES.FORM]: components.form || components.FormLayout || null,
+    [LAYOUT_TYPES.DASHBOARD]: components.dashboard || components.DashboardLayout || null,
+    [LAYOUT_TYPES.BASE]: components.base || components.BaseLayout || null,
+  }
+}
+
+/**
+ * Route meta object with layout
+ */
+export interface LayoutMeta {
+  layout: LayoutType
+}
+
+/**
+ * Get route meta configuration for layout
+ *
+ * Helper to add layout meta to route definitions
+ *
+ * @param layoutType - Layout type
+ * @returns Route meta object
+ *
+ * @example
+ * ```ts
+ * {
+ *   path: 'books',
+ *   name: 'book-list',
+ *   component: BookList,
+ *   meta: layoutMeta('list')
+ * }
+ * ```
+ */
+export function layoutMeta(layoutType: LayoutType): LayoutMeta {
+  return { layout: layoutType }
+}