@quazardous/qdadm 1.19.3

package/src/styles/theme/_tokens.scss

@@ -0,0 +1,147 @@
+/**
+ * Design Tokens - CSS Custom Properties
+ *
+ * Generates CSS custom properties (--fad-*) from SCSS variables.
+ * These tokens map to PrimeVue theme variables for consistency.
+ */
+
+@use '../variables' as *;
+
+:root {
+  // ===========================================================================
+  // Colors - Semantic
+  // ===========================================================================
+
+  // Text colors
+  --fad-text-primary: var(--p-text-color);
+  --fad-text-secondary: var(--p-text-muted-color);
+  --fad-text-disabled: var(--p-surface-400);
+  --fad-text-inverse: var(--p-surface-0);
+
+  // Surface colors (backgrounds, cards, overlays)
+  --fad-surface-ground: var(--p-surface-ground);
+  --fad-surface-card: var(--p-surface-card);
+  --fad-surface-overlay: var(--p-surface-overlay);
+  --fad-surface-border: var(--p-surface-200);
+  --fad-surface-hover: var(--p-surface-100);
+
+  // Primary brand color
+  --fad-primary: var(--p-primary-color);
+  --fad-primary-hover: var(--p-primary-600);
+  --fad-primary-text: var(--p-primary-contrast-color);
+
+  // Status colors
+  --fad-success: var(--p-green-500);
+  --fad-warning: var(--p-orange-500);
+  --fad-danger: var(--p-red-500);
+  --fad-info: var(--p-blue-500);
+
+  // ===========================================================================
+  // Spacing
+  // ===========================================================================
+
+  --fad-space-2xs: #{$space-2xs};
+  --fad-space-xs: #{$space-xs};
+  --fad-space-sm: #{$space-sm};
+  --fad-space-md: #{$space-md};
+  --fad-space-lg: #{$space-lg};
+  --fad-space-xl: #{$space-xl};
+  --fad-space-2xl: #{$space-2xl};
+
+  // ===========================================================================
+  // Typography
+  // ===========================================================================
+
+  --fad-font-family: #{$font-family-base};
+
+  // Font sizes
+  --fad-font-size-2xs: #{$font-size-2xs};
+  --fad-font-size-xs: #{$font-size-xs};
+  --fad-font-size-sm: #{$font-size-sm};
+  --fad-font-size-md: #{$font-size-md};
+  --fad-font-size-lg: #{$font-size-lg};
+  --fad-font-size-xl: #{$font-size-xl};
+  --fad-font-size-2xl: #{$font-size-2xl};
+
+  // Font weights
+  --fad-font-weight-light: #{$font-weight-light};
+  --fad-font-weight-normal: #{$font-weight-normal};
+  --fad-font-weight-medium: #{$font-weight-medium};
+  --fad-font-weight-semibold: #{$font-weight-semibold};
+  --fad-font-weight-bold: #{$font-weight-bold};
+
+  // Line heights
+  --fad-line-height-tight: #{$line-height-tight};
+  --fad-line-height-normal: #{$line-height-normal};
+  --fad-line-height-relaxed: #{$line-height-relaxed};
+
+  // ===========================================================================
+  // Borders & Radius
+  // ===========================================================================
+
+  --fad-border-width: #{$border-width};
+  --fad-border-color: var(--fad-surface-border);
+
+  --fad-radius-sm: #{$radius-sm};
+  --fad-radius-md: #{$radius-md};
+  --fad-radius-lg: #{$radius-lg};
+  --fad-radius-xl: #{$radius-xl};
+  --fad-radius-full: #{$radius-full};
+
+  // ===========================================================================
+  // Shadows
+  // ===========================================================================
+
+  --fad-shadow-sm: #{$shadow-sm};
+  --fad-shadow-md: #{$shadow-md};
+  --fad-shadow-lg: #{$shadow-lg};
+  --fad-shadow-xl: #{$shadow-xl};
+
+  // ===========================================================================
+  // Transitions
+  // ===========================================================================
+
+  --fad-transition-instant: #{$transition-instant};
+  --fad-transition-fast: #{$transition-fast};
+  --fad-transition-normal: #{$transition-normal};
+  --fad-transition-slow: #{$transition-slow};
+
+  // ===========================================================================
+  // Z-Index
+  // ===========================================================================
+
+  --fad-z-dropdown: #{$z-dropdown};
+  --fad-z-sticky: #{$z-sticky};
+  --fad-z-fixed: #{$z-fixed};
+  --fad-z-modal-backdrop: #{$z-modal-backdrop};
+  --fad-z-modal: #{$z-modal};
+  --fad-z-popover: #{$z-popover};
+  --fad-z-tooltip: #{$z-tooltip};
+
+  // ===========================================================================
+  // Layout
+  // ===========================================================================
+
+  --fad-sidebar-width: #{$sidebar-width};
+  --fad-sidebar-width-tablet: #{$sidebar-width-tablet};
+  --fad-sidebar-width-collapsed: #{$sidebar-width-collapsed};
+  --fad-header-height: #{$header-height};
+  --fad-content-max-width: #{$content-max-width};
+
+  // ===========================================================================
+  // Navigation
+  // ===========================================================================
+
+  --fad-nav-item-height: #{$nav-item-height};
+  --fad-nav-item-padding-x: #{$nav-item-padding-x};
+  --fad-nav-item-padding-y: #{$nav-item-padding-y};
+  --fad-nav-icon-size: #{$nav-icon-size};
+  --fad-nav-section-gap: #{$nav-section-gap};
+}
+
+// Dark mode overrides
+.dark-mode {
+  --fad-surface-border: var(--p-surface-700);
+  --fad-surface-hover: var(--p-surface-800);
+  --fad-text-disabled: var(--p-surface-500);
+}

package/src/styles/theme/_utilities.scss

@@ -0,0 +1,175 @@
+/**
+ * Utility Classes
+ *
+ * Minimal utility classes for common patterns.
+ * Keep it small - use components for complex layouts.
+ */
+
+@use '../variables' as *;
+
+// =============================================================================
+// Display
+// =============================================================================
+
+.d-none { display: none !important; }
+.d-block { display: block !important; }
+.d-flex { display: flex !important; }
+.d-inline-flex { display: inline-flex !important; }
+.d-grid { display: grid !important; }
+
+// =============================================================================
+// Flexbox
+// =============================================================================
+
+.flex-row { flex-direction: row; }
+.flex-column { flex-direction: column; }
+.flex-wrap { flex-wrap: wrap; }
+.flex-1 { flex: 1; }
+.flex-auto { flex: auto; }
+.flex-none { flex: none; }
+
+.items-start { align-items: flex-start; }
+.items-center { align-items: center; }
+.items-end { align-items: flex-end; }
+.items-stretch { align-items: stretch; }
+
+.justify-start { justify-content: flex-start; }
+.justify-center { justify-content: center; }
+.justify-end { justify-content: flex-end; }
+.justify-between { justify-content: space-between; }
+.justify-around { justify-content: space-around; }
+
+.gap-xs { gap: $space-xs; }
+.gap-sm { gap: $space-sm; }
+.gap-md { gap: $space-md; }
+.gap-lg { gap: $space-lg; }
+.gap-xl { gap: $space-xl; }
+
+// =============================================================================
+// Width
+// =============================================================================
+
+.w-full { width: 100% !important; }
+.w-auto { width: auto !important; }
+.w-50 { width: 50%; }
+.max-w-full { max-width: 100%; }
+
+// =============================================================================
+// Spacing (Margin/Padding)
+// =============================================================================
+
+// Margin
+.m-0 { margin: 0; }
+.m-auto { margin: auto; }
+
+.mt-0 { margin-top: 0; }
+.mt-xs { margin-top: $space-xs; }
+.mt-sm { margin-top: $space-sm; }
+.mt-md { margin-top: $space-md; }
+.mt-lg { margin-top: $space-lg; }
+.mt-xl { margin-top: $space-xl; }
+
+.mb-0 { margin-bottom: 0; }
+.mb-xs { margin-bottom: $space-xs; }
+.mb-sm { margin-bottom: $space-sm; }
+.mb-md { margin-bottom: $space-md; }
+.mb-lg { margin-bottom: $space-lg; }
+.mb-xl { margin-bottom: $space-xl; }
+
+.ml-auto { margin-left: auto; }
+.mr-auto { margin-right: auto; }
+.mx-auto { margin-left: auto; margin-right: auto; }
+
+// Padding
+.p-0 { padding: 0; }
+.p-xs { padding: $space-xs; }
+.p-sm { padding: $space-sm; }
+.p-md { padding: $space-md; }
+.p-lg { padding: $space-lg; }
+.p-xl { padding: $space-xl; }
+
+.px-md { padding-left: $space-md; padding-right: $space-md; }
+.py-md { padding-top: $space-md; padding-bottom: $space-md; }
+
+// =============================================================================
+// Text
+// =============================================================================
+
+.text-left { text-align: left; }
+.text-center { text-align: center; }
+.text-right { text-align: right; }
+
+.text-xs { font-size: $font-size-xs; }
+.text-sm { font-size: $font-size-sm; }
+.text-md { font-size: $font-size-md; }
+.text-lg { font-size: $font-size-lg; }
+.text-xl { font-size: $font-size-xl; }
+.text-2xl { font-size: $font-size-2xl; }
+
+.font-normal { font-weight: $font-weight-normal; }
+.font-medium { font-weight: $font-weight-medium; }
+.font-semibold { font-weight: $font-weight-semibold; }
+.font-bold { font-weight: $font-weight-bold; }
+
+.text-primary { color: var(--fad-text-primary); }
+.text-secondary { color: var(--fad-text-secondary); }
+.text-muted { color: var(--fad-text-secondary); }
+.text-success { color: var(--fad-success); }
+.text-warning { color: var(--fad-warning); }
+.text-danger { color: var(--fad-danger); }
+
+.truncate {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+// =============================================================================
+// Visibility
+// =============================================================================
+
+.visible { visibility: visible; }
+.invisible { visibility: hidden; }
+.opacity-0 { opacity: 0; }
+.opacity-50 { opacity: 0.5; }
+.opacity-100 { opacity: 1; }
+
+// =============================================================================
+// Borders
+// =============================================================================
+
+.border { border: $border-width solid var(--fad-border-color); }
+.border-0 { border: none; }
+.border-top { border-top: $border-width solid var(--fad-border-color); }
+.border-bottom { border-bottom: $border-width solid var(--fad-border-color); }
+
+.rounded-sm { border-radius: $radius-sm; }
+.rounded-md { border-radius: $radius-md; }
+.rounded-lg { border-radius: $radius-lg; }
+.rounded-full { border-radius: $radius-full; }
+
+// =============================================================================
+// Cursor
+// =============================================================================
+
+.cursor-pointer { cursor: pointer; }
+.cursor-default { cursor: default; }
+.cursor-not-allowed { cursor: not-allowed; }
+
+// =============================================================================
+// Overflow
+// =============================================================================
+
+.overflow-hidden { overflow: hidden; }
+.overflow-auto { overflow: auto; }
+.overflow-y-auto { overflow-y: auto; }
+.overflow-x-auto { overflow-x: auto; }
+
+// =============================================================================
+// Position
+// =============================================================================
+
+.relative { position: relative; }
+.absolute { position: absolute; }
+.fixed { position: fixed; }
+.sticky { position: sticky; }

package/src/toast/ToastBridgeModule.ts

@@ -0,0 +1,68 @@
+/**
+ * ToastBridgeModule - Bridges signal bus to PrimeVue Toast
+ *
+ * This module integrates toast functionality via the signal bus:
+ * - Registers ToastListener component to handle toast:* signals
+ * - Provides useSignalToast() composable for emitting toasts
+ *
+ * Usage in modules:
+ *   import { useSignalToast } from '@quazardous/qdadm'
+ *   const toast = useSignalToast()
+ *   toast.success('Saved!', 'Your changes have been saved')
+ *   toast.error('Error', 'Something went wrong')
+ *
+ * @example
+ * import { createKernel, ToastBridgeModule } from '@quazardous/qdadm'
+ *
+ * const kernel = createKernel()
+ * kernel.use(new ToastBridgeModule())
+ * await kernel.boot()
+ */
+
+import { Module } from '../kernel/Module'
+import type { KernelContext } from '../kernel/KernelContext'
+import ToastListener from './ToastListener.vue'
+
+/**
+ * Zone name for toast listener component
+ * Prefixed with _ to hide from ZonesCollector (internal zone)
+ */
+export const TOAST_ZONE = '_app:toasts'
+
+/**
+ * ToastBridgeModule - Handles toast notifications via signals
+ */
+export class ToastBridgeModule extends Module {
+  /**
+   * Module identifier
+   */
+  static override moduleName = 'toast-bridge'
+
+  /**
+   * No dependencies
+   */
+  static override requires: string[] = []
+
+  /**
+   * High priority - should load early
+   */
+  static override priority = 10
+
+  /**
+   * Connect module to kernel
+   * @param ctx - Kernel context
+   */
+  async connect(ctx: KernelContext): Promise<void> {
+    // Define the toast zone
+    ctx.zone(TOAST_ZONE)
+
+    // Register ToastListener component in the zone
+    ctx.block(TOAST_ZONE, {
+      id: 'toast-listener',
+      component: ToastListener,
+      weight: 0,
+    })
+  }
+}
+
+export default ToastBridgeModule

package/src/toast/ToastListener.vue

@@ -0,0 +1,55 @@
+<script setup lang="ts">
+/**
+ * ToastListener - Bridges signal bus to PrimeVue Toast
+ *
+ * Invisible component that listens to toast:* signals and displays
+ * them using PrimeVue's Toast component.
+ *
+ * This component should be registered in a zone via ToastBridgeModule.
+ */
+import { onMounted, onUnmounted, inject } from 'vue'
+import { useToast } from 'primevue/usetoast'
+import type { SignalBus } from '../kernel/SignalBus'
+
+interface ToastEventData {
+  summary?: string
+  detail?: string
+  life?: number
+}
+
+const toast = useToast()
+const signals = inject<SignalBus | null>('qdadmSignals', null)
+
+let unsubscribe: (() => void) | null = null
+
+onMounted(() => {
+  if (!signals) {
+    console.warn('[ToastListener] No signals bus injected')
+    return
+  }
+
+  // Listen to all toast signals
+  unsubscribe = signals.on('toast:*', (event) => {
+    const data = event.data as ToastEventData | undefined
+    const severity = event.name.split(':')[1] // toast:success -> success
+    toast.add({
+      severity,
+      summary: data?.summary,
+      detail: data?.detail,
+      life: data?.life ?? 3000
+    })
+  })
+})
+
+onUnmounted(() => {
+  if (unsubscribe) {
+    unsubscribe()
+    unsubscribe = null
+  }
+})
+</script>
+
+<template>
+  <!-- Invisible listener component -->
+  <span style="display: none" />
+</template>

package/src/toast/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Toast Module - Signal-based toast notifications
+ *
+ * Provides toast notifications that go through the signal bus,
+ * allowing for proper debugging and interception.
+ *
+ * Components:
+ * - ToastBridgeModule: Registers ToastListener for handling signals
+ * - ToastListener: Vue component that displays toasts via PrimeVue
+ * - useSignalToast: Composable for emitting toast signals
+ */
+
+export {
+  ToastBridgeModule,
+  TOAST_ZONE,
+} from './ToastBridgeModule'
+
+export {
+  useSignalToast,
+  type ToastSeverity,
+  type ToastOptions,
+  type ToastMethodOptions,
+  type SignalToastAPI,
+} from './useSignalToast'
+
+export { default as ToastListener } from './ToastListener.vue'

package/src/toast/useSignalToast.ts

@@ -0,0 +1,154 @@
+/**
+ * useSignalToast - Composable for emitting toast notifications via signals
+ *
+ * This composable provides a simple API for showing toasts that go through
+ * the signal bus. Works with ToastBridgeModule which handles displaying
+ * the toasts via PrimeVue.
+ *
+ * @example
+ * import { useSignalToast } from '@quazardous/qdadm'
+ *
+ * // With explicit emitter name
+ * const toast = useSignalToast('MyComponent')
+ * toast.success('Saved!', 'Your changes have been saved')
+ *
+ * // Without emitter (defaults to 'unknown')
+ * const toast = useSignalToast()
+ * toast.error('Error', 'Something went wrong')
+ */
+
+import { inject, getCurrentInstance } from 'vue'
+import type { SignalBus } from '../kernel/SignalBus'
+
+/**
+ * Toast severity types
+ */
+export type ToastSeverity = 'success' | 'info' | 'warn' | 'error'
+
+/**
+ * Toast options for the add method
+ */
+export interface ToastOptions {
+  severity?: ToastSeverity
+  summary: string
+  detail?: string
+  life?: number
+  /** Force classic PrimeVue toast even when NotificationModule is active */
+  forceToast?: boolean
+}
+
+/**
+ * Toast method options
+ */
+export interface ToastMethodOptions {
+  /** Force classic PrimeVue toast even when NotificationModule is active */
+  forceToast?: boolean
+}
+
+/**
+ * Toast API returned by useSignalToast
+ */
+export interface SignalToastAPI {
+  success: (summary: string, detail?: string, life?: number, options?: ToastMethodOptions) => void
+  error: (summary: string, detail?: string, life?: number, options?: ToastMethodOptions) => void
+  info: (summary: string, detail?: string, life?: number, options?: ToastMethodOptions) => void
+  warn: (summary: string, detail?: string, life?: number, options?: ToastMethodOptions) => void
+  add: (options: ToastOptions) => void
+}
+
+/**
+ * Composable for emitting toast notifications via signal bus
+ * @param emitter - Identifier for the toast source (component/module name)
+ * @returns Toast API
+ */
+export function useSignalToast(emitter?: string): SignalToastAPI {
+  const injectedSignals = inject<SignalBus | undefined>('qdadmSignals')
+
+  // Try to auto-detect emitter from current component if not provided
+  const instance = getCurrentInstance()
+  const componentType = instance?.type as { name?: string; __name?: string } | undefined
+  const resolvedEmitter = emitter || componentType?.name || componentType?.__name || 'unknown'
+
+  if (!injectedSignals) {
+    console.warn('[useSignalToast] No signals bus injected - toasts will not work')
+    // Return no-op functions
+    return {
+      success: () => {},
+      error: () => {},
+      info: () => {},
+      warn: () => {},
+      add: () => {},
+    }
+  }
+
+  // Capture signals after null check for closure
+  const signals = injectedSignals
+
+  /**
+   * Show a toast notification
+   * @param severity - Toast severity (success, info, warn, error)
+   * @param summary - Toast title
+   * @param detail - Toast detail message
+   * @param life - Duration in ms (0 for sticky)
+   * @param forceToast - Force classic PrimeVue toast when NotificationModule is active
+   */
+  function addToast(severity: ToastSeverity, summary: string, detail?: string, life: number = 3000, forceToast?: boolean): void {
+    signals.emit(`toast:${severity}`, { summary, detail, life, emitter: resolvedEmitter, forceToast })
+  }
+
+  return {
+    /**
+     * Show success toast
+     * @param summary - Toast title
+     * @param detail - Toast detail message
+     * @param life - Duration in ms
+     * @param options - Additional options
+     */
+    success(summary: string, detail?: string, life: number = 3000, options?: ToastMethodOptions): void {
+      addToast('success', summary, detail, life, options?.forceToast)
+    },
+
+    /**
+     * Show error toast
+     * @param summary - Toast title
+     * @param detail - Toast detail message
+     * @param life - Duration in ms (longer for errors)
+     * @param options - Additional options
+     */
+    error(summary: string, detail?: string, life: number = 5000, options?: ToastMethodOptions): void {
+      addToast('error', summary, detail, life, options?.forceToast)
+    },
+
+    /**
+     * Show info toast
+     * @param summary - Toast title
+     * @param detail - Toast detail message
+     * @param life - Duration in ms
+     * @param options - Additional options
+     */
+    info(summary: string, detail?: string, life: number = 3000, options?: ToastMethodOptions): void {
+      addToast('info', summary, detail, life, options?.forceToast)
+    },
+
+    /**
+     * Show warning toast
+     * @param summary - Toast title
+     * @param detail - Toast detail message
+     * @param life - Duration in ms
+     * @param options - Additional options
+     */
+    warn(summary: string, detail?: string, life: number = 4000, options?: ToastMethodOptions): void {
+      addToast('warn', summary, detail, life, options?.forceToast)
+    },
+
+    /**
+     * Generic add method (compatible with PrimeVue toast.add)
+     * @param options - Toast options
+     */
+    add(options: ToastOptions): void {
+      addToast(options.severity || 'info', options.summary, options.detail, options.life, options.forceToast)
+    },
+  }
+}
+
+export default useSignalToast