@quazardous/qdadm 1.19.3

package/src/chain/useStackHydrator.ts

@@ -0,0 +1,155 @@
+/**
+ * useStackHydrator - Access hydrated navigation stack
+ *
+ * Provides async-hydrated levels with entity data and labels.
+ * Each level has its own promise for fine-grained control.
+ *
+ * Listens to SignalBus events for reactivity:
+ * - stack:hydrated - when hydration completes (batched)
+ *
+ * @example
+ * const hydrator = useStackHydrator()
+ *
+ * // Reactive usage (shows loading state, updates when ready)
+ * const parentLabel = computed(() =>
+ *   hydrator.parent.value?.hydrated
+ *     ? hydrator.parent.value.label
+ *     : 'Loading...'
+ * )
+ *
+ * // Await specific level
+ * await hydrator.getParent()?.promise
+ *
+ * // Await all levels
+ * await Promise.all(hydrator.getLevels().map(l => l.promise))
+ */
+
+import { inject, ref, computed, onUnmounted, type Ref, type ComputedRef } from 'vue'
+import type { SignalBus } from '../kernel/SignalBus'
+
+/**
+ * Hydrated level data
+ */
+export interface HydratedLevel {
+  entity: string
+  id: string | number
+  data: unknown | null
+  label: string | null
+  hydrated: boolean
+  promise: Promise<unknown>
+}
+
+/**
+ * Stack hydrator interface (from StackHydrator class)
+ */
+interface StackHydratorClass {
+  getLevels: () => HydratedLevel[]
+  getLevel: (index: number) => HydratedLevel | null
+  getLevelByEntity: (entity: string) => HydratedLevel | null
+  getCurrent: () => HydratedLevel | null
+  getParent: () => HydratedLevel | null
+  setCurrentData: (data: unknown) => void
+  setEntityData: (entity: string, data: unknown) => void
+}
+
+/**
+ * Return type for useStackHydrator
+ */
+export interface StackHydratorReturn {
+  // Computed refs (reactive)
+  levels: Ref<HydratedLevel[]>
+  current: ComputedRef<HydratedLevel | null>
+  parent: ComputedRef<HydratedLevel | null>
+  root: ComputedRef<HydratedLevel | null>
+
+  // Sync accessors (for immediate access + promise)
+  getLevel: (index: number) => HydratedLevel | null
+  getLevelByEntity: (entity: string) => HydratedLevel | null
+  getCurrent: () => HydratedLevel | null
+  getParent: () => HydratedLevel | null
+  getLevels: () => HydratedLevel[]
+
+  // Manual data setters (for pages that load their own data)
+  setCurrentData: (data: unknown) => void
+  setEntityData: (entity: string, data: unknown) => void
+}
+
+export function useStackHydrator(): StackHydratorReturn {
+  const hydrator = inject<StackHydratorClass | null>('qdadmStackHydrator', null)
+  const signalBus = inject<SignalBus | null>('qdadmSignals', null)
+
+  if (!hydrator) {
+    console.warn('[useStackHydrator] StackHydrator not provided')
+    return createEmptyHydrator()
+  }
+
+  // Reactive state - updated via SignalBus
+  const levels = ref<HydratedLevel[]>(hydrator.getLevels())
+
+  // Subscribe to hydration changes (batched signal)
+  // QuarKernel passes (event, ctx) where event.data contains the payload
+  let unsubscribe: (() => void) | null = null
+  if (signalBus) {
+    const handler = (event: unknown): void => {
+      const eventData = event as { data?: { levels?: HydratedLevel[] } }
+      const newLevels = eventData.data?.levels
+      if (newLevels) {
+        // Create new array reference to trigger reactivity
+        levels.value = [...newLevels]
+      }
+    }
+    unsubscribe = signalBus.on('stack:hydrated', handler)
+  }
+
+  // Cleanup on unmount
+  onUnmounted(() => {
+    if (unsubscribe) {
+      unsubscribe()
+    }
+  })
+
+  // Computed accessors
+  const current = computed(() => levels.value.at(-1) ?? null)
+  const parent = computed(() => levels.value.at(-2) ?? null)
+  const root = computed(() => levels.value[0] ?? null)
+
+  return {
+    // Computed refs (reactive)
+    levels,
+    current,
+    parent,
+    root,
+
+    // Sync accessors (for immediate access + promise)
+    getLevel: (i: number) => hydrator.getLevel(i),
+    getLevelByEntity: (e: string) => hydrator.getLevelByEntity(e),
+    getCurrent: () => hydrator.getCurrent(),
+    getParent: () => hydrator.getParent(),
+    getLevels: () => hydrator.getLevels(),
+
+    // Manual data setters (for pages that load their own data)
+    setCurrentData: (data: unknown) => hydrator.setCurrentData(data),
+    setEntityData: (entity: string, data: unknown) => hydrator.setEntityData(entity, data),
+  }
+}
+
+/**
+ * Fallback when StackHydrator not available
+ */
+function createEmptyHydrator(): StackHydratorReturn {
+  return {
+    levels: ref<HydratedLevel[]>([]),
+    current: computed(() => null),
+    parent: computed(() => null),
+    root: computed(() => null),
+    getLevel: () => null,
+    getLevelByEntity: () => null,
+    getCurrent: () => null,
+    getParent: () => null,
+    getLevels: () => [],
+    setCurrentData: () => {},
+    setEntityData: () => {},
+  }
+}
+
+export default useStackHydrator

package/src/components/BoolCell.vue

@@ -0,0 +1,34 @@
+<script setup lang="ts">
+/**
+ * BoolCell - Standardized boolean display for list columns
+ *
+ * Tristate display:
+ * - true / "true" / 1: green check
+ * - false / "false" / 0: red cross
+ * - null/undefined: empty
+ *
+ * Usage:
+ * <Column field="read" header="Read">
+ *   <template #body="{ data }">
+ *     <BoolCell :value="data.read" />
+ *   </template>
+ * </Column>
+ */
+import { computed } from 'vue'
+
+interface Props {
+  value?: boolean | string | number | null
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  value: null
+})
+
+const isTrue = computed(() => props.value === true || props.value === 'true' || props.value === 1)
+const isFalse = computed(() => props.value === false || props.value === 'false' || props.value === 0)
+</script>
+
+<template>
+  <i v-if="isTrue" class="pi pi-check" style="color: var(--p-green-500)" />
+  <i v-else-if="isFalse" class="pi pi-times" style="color: var(--p-red-500)" />
+</template>

package/src/components/InfoBanner.vue

@@ -0,0 +1,73 @@
+<script setup lang="ts">
+/**
+ * InfoBanner - Consistent message banner component
+ *
+ * Wraps PrimeVue Message with standardized styling and icon support.
+ *
+ * @example
+ * // Simple usage
+ * <InfoBanner severity="warn">
+ *   Settings will be lost on refresh.
+ * </InfoBanner>
+ *
+ * // With custom icon
+ * <InfoBanner severity="success" icon="pi-check-circle">
+ *   Operation completed successfully.
+ * </InfoBanner>
+ *
+ * // Without icon
+ * <InfoBanner severity="info" :icon="false">
+ *   Just some information.
+ * </InfoBanner>
+ */
+import Message from 'primevue/message'
+import { computed } from 'vue'
+
+type Severity = 'info' | 'success' | 'warn' | 'error' | 'secondary' | 'contrast'
+
+interface Props {
+  /** Severity level: info, success, warn, error, secondary, contrast */
+  severity?: Severity
+  /** Custom icon class (e.g., 'pi-user'). Set to false to hide icon. */
+  icon?: string | boolean | null
+  /** Allow closing the banner (default: true) */
+  closable?: boolean
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  severity: 'info',
+  icon: null,
+  closable: true
+})
+
+// Default icons per severity
+const defaultIcons: Record<Severity, string> = {
+  info: 'pi-info-circle',
+  success: 'pi-check-circle',
+  warn: 'pi-exclamation-triangle',
+  error: 'pi-times-circle',
+  secondary: 'pi-info-circle',
+  contrast: 'pi-info-circle'
+}
+
+const iconClass = computed(() => {
+  if (props.icon === false) return null
+  if (props.icon && typeof props.icon === 'string') return `pi ${props.icon}`
+  return `pi ${defaultIcons[props.severity]}`
+})
+</script>
+
+<template>
+  <Message
+    :severity="severity"
+    :closable="closable"
+    class="info-banner"
+  >
+    <div class="info-banner-content">
+      <i v-if="iconClass" :class="iconClass" class="info-banner-icon"></i>
+      <span class="info-banner-text">
+        <slot />
+      </span>
+    </div>
+  </Message>
+</template>

package/src/components/QdadmRoot.vue

@@ -0,0 +1,52 @@
+<script setup lang="ts">
+/**
+ * QdadmRoot — drop-in helper for hosts that own their own Vue app
+ * and want qdadm's DOM extras (Toast, ToastListener, DebugBar)
+ * rendered alongside.
+ *
+ * Equivalent to the wrapper Kernel produces internally when it owns
+ * `createApp`. When `Kernel({ existingApp })` is used, the host's
+ * App.vue should render `<QdadmRoot />` somewhere visible (typically
+ * at the end of the template) so toasts and the debug bar appear.
+ *
+ * The Toast / DebugBar children are conditional on what the Kernel
+ * was configured with (PrimeVue presence, debugBar option) — render
+ * is a no-op otherwise, so it's always safe to include.
+ */
+
+import { computed, inject, type Component } from 'vue'
+import Toast from 'primevue/toast'
+import ToastListener from '../toast/ToastListener.vue'
+import { getQdadmDebugBarRef } from '../kernel/Kernel.vue'
+
+const props = withDefaults(
+  defineProps<{
+    /**
+     * Render the qdadm debug bar inline. Default true preserves the
+     * legacy behaviour. Set false in hosts that already render their
+     * own (shared) `<DebugBar />` to avoid two bars on screen.
+     */
+    debugBar?: boolean
+  }>(),
+  { debugBar: true },
+)
+
+// Read the singleton-on-window debug bar ref. Using a getter (instead
+// of importing the module-level const) makes this resilient to Vite
+// HMR's module fragmentation in dev, where a top-level `const ref`
+// can be torn into separate instances per importer.
+const debugBarRef = getQdadmDebugBarRef()
+const debugBarComp = computed<Component | null>(() =>
+  props.debugBar ? debugBarRef.value : null,
+)
+
+// `qdadmHasPrimeVue` is provided by the Kernel during _installPlugins.
+// True when PrimeVue is wired (so Toast / ToastListener are usable).
+const hasToast = inject<boolean>('qdadmHasPrimeVue', false)
+</script>
+
+<template>
+  <Toast v-if="hasToast" />
+  <ToastListener v-if="hasToast" />
+  <component v-if="debugBarComp" :is="debugBarComp" />
+</template>

package/src/components/SeverityTag.vue

@@ -0,0 +1,86 @@
+<script setup lang="ts">
+/**
+ * SeverityTag - Auto-discovers severity from EntityManager
+ *
+ * Renders a PrimeVue Tag for simple severity strings, or a rich badge
+ * with icon (including animated spinners) when the severity map provides
+ * a descriptor with an `icon` field.
+ *
+ * Entity can be specified explicitly or auto-discovered from list context.
+ *
+ * @example
+ * // Explicit entity
+ * <SeverityTag entity="jobs" field="status" :value="job.status" />
+ *
+ * // Auto-discover from list context (inside ListPage)
+ * <SeverityTag field="status" :value="data.status" />
+ *
+ * // With custom label
+ * <SeverityTag entity="stories" field="status" :value="story.status" label="Published" />
+ */
+import { computed, inject } from 'vue'
+import Tag from 'primevue/tag'
+import type { Orchestrator } from '../orchestrator/Orchestrator'
+import type { EntityManager } from '../entity/EntityManager'
+
+interface Props {
+  /** Entity name (e.g., 'jobs', 'stories') - optional if inside ListPage context */
+  entity?: string | null
+  /** Field name for severity lookup (e.g., 'status') */
+  field: string
+  /** Field value */
+  value?: string | number | boolean | null
+  /** Optional custom label (defaults to value) */
+  label?: string | null
+  /** Default severity if no mapping found */
+  defaultSeverity?: string
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  entity: null,
+  value: null,
+  label: null,
+  defaultSeverity: 'secondary'
+})
+
+const orchestrator = inject<Orchestrator | null>('qdadmOrchestrator', null)
+// Auto-discover entity from page context (provided by useListPage, useBareForm, etc.)
+const mainEntity = inject<string | null>('mainEntity', null)
+
+const resolvedEntity = computed(() => props.entity || mainEntity)
+
+const manager = computed<EntityManager | null>(() => {
+  if (!resolvedEntity.value) return null
+  return orchestrator?.get(resolvedEntity.value) ?? null
+})
+
+const fieldValue = computed(() => {
+  if (props.value === null || props.value === undefined) return ''
+  return typeof props.value === 'boolean' ? String(props.value) : props.value
+})
+
+const descriptor = computed(() => {
+  if (!manager.value?.getSeverityDescriptor) {
+    return { severity: manager.value?.getSeverity?.(props.field, fieldValue.value as string | number, props.defaultSeverity) ?? props.defaultSeverity }
+  }
+  return manager.value.getSeverityDescriptor(props.field, fieldValue.value as string | number, props.defaultSeverity)
+})
+
+const severity = computed(() => descriptor.value.severity)
+
+const displayLabel = computed(() => {
+  return props.label ?? descriptor.value.label ?? props.value
+})
+
+const hasIcon = computed(() => !!descriptor.value.icon)
+</script>
+
+<template>
+  <!-- Rich badge with icon -->
+  <span v-if="hasIcon" class="p-tag p-component" :class="`p-tag-${severity}`">
+    <i :class="descriptor.icon" />
+    <span class="p-tag-label">{{ displayLabel }}</span>
+  </span>
+  <!-- Simple PrimeVue Tag -->
+  <Tag v-else :value="displayLabel" :severity="severity" />
+</template>

package/src/components/dialogs/BulkStatusDialog.vue

@@ -0,0 +1,60 @@
+<script setup lang="ts">
+import SimpleDialog from './SimpleDialog.vue'
+import Select from 'primevue/select'
+
+interface StatusOption {
+  label: string
+  value: string | number
+}
+
+interface Props {
+  visible?: boolean
+  title?: string
+  options: StatusOption[]
+  modelValue?: string | number
+  loading?: boolean
+  selectionCount?: number
+}
+
+withDefaults(defineProps<Props>(), {
+  visible: false,
+  title: 'Change Status',
+  loading: false,
+  selectionCount: 0
+})
+
+defineEmits<{
+  'update:visible': [value: boolean]
+  'update:modelValue': [value: string | number]
+  confirm: []
+  cancel: []
+}>()
+</script>
+
+<template>
+  <SimpleDialog
+    :visible="visible"
+    :title="title"
+    width="400px"
+    :loading="loading"
+    confirmLabel="Update"
+    confirmIcon="pi pi-check"
+    :confirmDisabled="!modelValue"
+    @update:visible="$emit('update:visible', $event)"
+    @confirm="$emit('confirm')"
+    @cancel="$emit('cancel')"
+  >
+    <p v-if="selectionCount > 0" class="mb-3">
+      Change status for {{ selectionCount }} selected item(s):
+    </p>
+    <Select
+      :modelValue="modelValue"
+      :options="options"
+      optionLabel="label"
+      optionValue="value"
+      placeholder="Select new status"
+      class="w-full"
+      @update:modelValue="$emit('update:modelValue', $event)"
+    />
+  </SimpleDialog>
+</template>