qdadm 0.13.0 → 0.14.1

package/README.md

@@ -1,14 +1,10 @@
 # qdadm
 
-Vue 3 framework for building admin dashboards with PrimeVue.
+**Vue 3 admin framework. PrimeVue. Zero boilerplate.**
 
-## Features
+Full documentation: [../../README.md](../../README.md)
 
-- **Kernel**: All-in-one bootstrap (Vue app, router, Pinia, PrimeVue, auth guard)
-- **EntityManager**: CRUD operations with permission control (`canRead`/`canCreate`/`canUpdate`/`canDelete`)
-- **Module System**: Auto-discovery of modules with routes and navigation
-- **Components**: Forms, lists, dialogs, editors ready to use
-- **Composables**: `useForm`, `useListPageBuilder`, `useBareForm`, etc.
+Changelog: [../../CHANGELOG.md](../../CHANGELOG.md)
 
 ## Installation
 
@@ -16,7 +12,7 @@ Vue 3 framework for building admin dashboards with PrimeVue.
 npm install qdadm
 ```
 
-## Quick Start with Kernel
+## Quick Start
 
 ```js
 import { Kernel, EntityManager, LocalStorage } from 'qdadm'
@@ -24,135 +20,48 @@ import PrimeVue from 'primevue/config'
 import Aura from '@primeuix/themes/aura'
 import 'qdadm/styles'
 
-import App from './App.vue'
-import { authAdapter } from './adapters/authAdapter'
-
-const managers = {
-  books: new EntityManager({
-    name: 'books',
-    storage: new LocalStorage({ key: 'my_books' }),
-    fields: {
-      title: { type: 'text', label: 'Title', required: true },
-      author: { type: 'text', label: 'Author' }
-    }
-  })
-}
-
 const kernel = new Kernel({
   root: App,
   modules: import.meta.glob('./modules/*/init.js', { eager: true }),
-  sectionOrder: ['Library'],
-  managers,
-  authAdapter,
-  pages: {
-    login: () => import('./pages/LoginPage.vue'),
-    layout: () => import('./pages/MainLayout.vue')
+  managers: {
+    books: new EntityManager({
+      name: 'books',
+      storage: new LocalStorage({ key: 'books' }),
+      labelField: 'title'
+    })
   },
+  authAdapter,
+  pages: { login: LoginPage, layout: MainLayout },
   homeRoute: 'book',
-  app: { name: 'My App', version: '1.0.0' },
+  app: { name: 'My App' },
   primevue: { plugin: PrimeVue, theme: Aura }
 })
 
 kernel.createApp().mount('#app')
 ```
 
-## Manual Bootstrap (without Kernel)
+## Exports
 
 ```js
-import { createQdadm, initModules, getRoutes } from 'qdadm'
-
-// Init modules
-initModules(import.meta.glob('./modules/*/init.js', { eager: true }))
-
-// Create router with getRoutes()
-const router = createRouter({
-  history: createWebHistory(),
-  routes: [
-    { path: '/login', component: LoginPage },
-    { path: '/', component: Layout, children: getRoutes() }
-  ]
-})
-
-// Install plugin
-app.use(createQdadm({ managers, authAdapter, router, toast }))
-```
+// Main
+import { Kernel, createQdadm, EntityManager, ApiStorage, LocalStorage } from 'qdadm'
 
-## Module Structure
+// Composables
+import { useForm, useBareForm, useListPageBuilder } from 'qdadm/composables'
 
-```
-modules/
-└── books/
-    ├── init.js          # Route & nav registration
-    └── pages/
-        ├── BookList.vue
-        └── BookForm.vue
-```
+// Components
+import { ListPage, PageLayout, FormField, FormActions } from 'qdadm/components'
 
-**init.js:**
-```js
-export function init(registry) {
-  registry.addRoutes('books', [
-    { path: '', name: 'book', component: () => import('./pages/BookList.vue') },
-    { path: 'create', name: 'book-create', component: () => import('./pages/BookForm.vue') },
-    { path: ':id/edit', name: 'book-edit', component: () => import('./pages/BookForm.vue') }
-  ], { entity: 'books' })
-
-  registry.addNavItem({
-    section: 'Library',
-    route: 'book',
-    icon: 'pi pi-book',
-    label: 'Books',
-    entity: 'books'
-  })
-
-  registry.addRouteFamily('book', ['book-'])
-}
-```
+// Module system
+import { initModules, getRoutes, setSectionOrder } from 'qdadm/module'
 
-## EntityManager Permissions
+// Utilities
+import { formatDate, truncate } from 'qdadm/utils'
 
-```js
-class UsersManager extends EntityManager {
-  canRead() {
-    return authAdapter.getUser()?.role === 'admin'
-  }
-  canCreate() {
-    return authAdapter.getUser()?.role === 'admin'
-  }
-  canUpdate(entity) {
-    return authAdapter.getUser()?.role === 'admin'
-  }
-  canDelete(entity) {
-    return authAdapter.getUser()?.role === 'admin'
-  }
-}
+// Styles
+import 'qdadm/styles'
 ```
 
-When `canRead()` returns false:
-- Navigation items are hidden
-- Routes redirect to `/`
-
-## Components
-
-| Category | Components |
-|----------|------------|
-| Layout | `AppLayout`, `PageLayout`, `PageHeader`, `Breadcrumb` |
-| Forms | `FormField`, `FormActions`, `FormTabs`, `FormTab` |
-| Lists | `ListPage`, `ActionButtons`, `FilterBar` |
-| Editors | `JsonViewer`, `KeyValueEditor`, `VanillaJsonEditor` |
-| Dialogs | `SimpleDialog`, `MultiStepDialog`, `UnsavedChangesDialog` |
-| Display | `CardsGrid`, `CopyableId`, `EmptyState` |
-
-## Composables
-
-| Composable | Description |
-|------------|-------------|
-| `useForm` | Form with validation, dirty state, navigation guard |
-| `useBareForm` | Lightweight form without routing |
-| `useListPageBuilder` | Paginated list with filters and actions |
-| `useTabSync` | Sync tabs with URL query params |
-| `useBreadcrumb` | Dynamic breadcrumb from route |
-
 ## Peer Dependencies
 
 - vue ^3.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qdadm",
-  "version": "0.13.0",
+  "version": "0.14.1",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",
@@ -25,7 +25,6 @@
   "files": [
     "src",
     "README.md",
-    "CHANGELOG.md",
     "LICENSE"
   ],
   "peerDependencies": {

package/src/components/SeverityTag.vue

@@ -0,0 +1,71 @@
+<script setup>
+/**
+ * SeverityTag - Auto-discovers severity from EntityManager
+ *
+ * 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'
+
+const props = defineProps({
+  // Entity name (e.g., 'jobs', 'stories') - optional if inside ListPage context
+  entity: {
+    type: String,
+    default: null
+  },
+  // Field name for severity lookup (e.g., 'status')
+  field: {
+    type: String,
+    required: true
+  },
+  // Field value
+  value: {
+    type: [String, Number, Boolean],
+    default: null
+  },
+  // Optional custom label (defaults to value)
+  label: {
+    type: String,
+    default: null
+  },
+  // Default severity if no mapping found
+  defaultSeverity: {
+    type: String,
+    default: 'secondary'
+  }
+})
+
+const orchestrator = inject('qdadmOrchestrator')
+// Auto-discover entity from page context (provided by useListPageBuilder, useBareForm, etc.)
+const mainEntity = inject('mainEntity', null)
+
+const resolvedEntity = computed(() => props.entity || mainEntity)
+
+const manager = computed(() => {
+  if (!resolvedEntity.value) return null
+  return orchestrator?.get(resolvedEntity.value)
+})
+
+const severity = computed(() => {
+  if (!manager.value) return props.defaultSeverity
+  return manager.value.getSeverity(props.field, props.value, props.defaultSeverity)
+})
+
+const displayLabel = computed(() => {
+  return props.label ?? props.value
+})
+</script>
+
+<template>
+  <Tag :value="displayLabel" :severity="severity" />
+</template>

package/src/components/editors/ScopeEditor.vue

@@ -20,7 +20,7 @@ const props = defineProps({
   },
   scopePrefix: {
     type: String,
-    default: 'faketual' // Prefix for scope strings (e.g., "faketual.resource:action")
+    default: 'app' // Prefix for scope strings (e.g., "app.resource:action")
   },
   // Default resources/actions if API not available
   defaultResources: {

package/src/components/index.js

@@ -42,3 +42,4 @@ export { default as CopyableId } from './display/CopyableId.vue'
 export { default as EmptyState } from './display/EmptyState.vue'
 export { default as IntensityBar } from './display/IntensityBar.vue'
 export { default as BoolCell } from './BoolCell.vue'
+export { default as SeverityTag } from './SeverityTag.vue'

package/src/components/layout/AppLayout.vue

@@ -18,12 +18,14 @@ import { useNavigation } from '../../composables/useNavigation'
 import { useApp } from '../../composables/useApp'
 import { useAuth } from '../../composables/useAuth'
 import { useGuardDialog } from '../../composables/useGuardStore'
+import { useBreadcrumb } from '../../composables/useBreadcrumb'
 import Button from 'primevue/button'
+import Breadcrumb from 'primevue/breadcrumb'
 import UnsavedChangesDialog from '../dialogs/UnsavedChangesDialog.vue'
 import qdadmLogo from '../../assets/logo.svg'
 import { version as qdadmVersion } from '../../../package.json'
 
-const features = inject('qdadmFeatures', { poweredBy: true })
+const features = inject('qdadmFeatures', { poweredBy: true, breadcrumb: true })
 
 // Guard dialog from shared store (registered by useBareForm/useForm when a form is active)
 const guardDialog = useGuardDialog()
@@ -122,6 +124,16 @@ function handleLogout() {
 // Check if slot content is provided
 const slots = useSlots()
 const hasSlotContent = computed(() => !!slots.default)
+
+// Breadcrumb (auto-generated from route)
+const { breadcrumbItems } = useBreadcrumb()
+// Show breadcrumb if enabled, has items, and not on home page
+const showBreadcrumb = computed(() => {
+  if (!features.breadcrumb || breadcrumbItems.value.length === 0) return false
+  // Don't show on home page (just "Dashboard" with no parents)
+  if (route.name === 'dashboard') return false
+  return true
+})
 </script>
 
 <template>
@@ -191,6 +203,20 @@ const hasSlotContent = computed(() => !!slots.default)
 
     <!-- Main content -->
     <main class="main-content">
+      <!-- Breadcrumb (auto-generated, can be disabled via features.breadcrumb: false) -->
+      <Breadcrumb v-if="showBreadcrumb" :model="breadcrumbItems" class="layout-breadcrumb">
+        <template #item="{ item }">
+          <RouterLink v-if="item.to" :to="item.to" class="breadcrumb-link">
+            <i v-if="item.icon" :class="item.icon"></i>
+            <span>{{ item.label }}</span>
+          </RouterLink>
+          <span v-else class="breadcrumb-current">
+            <i v-if="item.icon" :class="item.icon"></i>
+            <span>{{ item.label }}</span>
+          </span>
+        </template>
+      </Breadcrumb>
+
       <div class="page-content">
         <!-- Use slot if provided, otherwise RouterView for nested routes -->
         <slot v-if="hasSlotContent" />
@@ -390,6 +416,8 @@ const hasSlotContent = computed(() => !!slots.default)
   overflow-y: auto;
 }
 
+/* Breadcrumb styles are in main.css */
+
 /* Dark mode support */
 .dark-mode .sidebar {
   background: var(--p-surface-900);

package/src/components/layout/PageHeader.vue

@@ -3,19 +3,39 @@
  * PageHeader - Reusable page header with breadcrumb, title and actions
  *
  * Props:
- * - title: Page title (required)
+ * - title: Page title (simple string) OR
+ * - titleParts: { action, entityName, entityLabel } for decorated rendering
  * - breadcrumb: Array of { label, to?, icon? } - optional breadcrumb items
  *
+ * Title rendering:
+ * - Simple: "Edit Agent" → <h1>Edit Agent</h1>
+ * - Decorated: { action: 'Edit', entityName: 'Agent', entityLabel: 'David' }
+ *   → <h1>Edit Agent: <span class="entity-label">David</span></h1>
+ *
  * Slots:
  * - subtitle: Optional content next to title
  * - actions: Action buttons on the right
+ *
+ * Note: When features.breadcrumb is enabled in AppLayout, the layout handles
+ * breadcrumb rendering globally. PageHeader only renders its own breadcrumb
+ * when the global feature is disabled.
  */
+import { computed, inject } from 'vue'
 import Breadcrumb from './Breadcrumb.vue'
 
-defineProps({
+const features = inject('qdadmFeatures', { breadcrumb: false })
+
+// Auto-injected title from useForm (if available)
+const injectedTitleParts = inject('qdadmPageTitleParts', null)
+
+const props = defineProps({
   title: {
     type: String,
-    required: true
+    default: null
+  },
+  titleParts: {
+    type: Object,
+    default: null
   },
   subtitle: {
     type: String,
@@ -26,16 +46,42 @@ defineProps({
     default: null
   }
 })
+
+// Use props first, then injected, then fallback
+const effectiveTitleParts = computed(() => {
+  return props.titleParts || injectedTitleParts?.value || null
+})
+
+// Compute title display
+const hasDecoratedTitle = computed(() => {
+  return effectiveTitleParts.value?.entityLabel
+})
+
+const titleBase = computed(() => {
+  if (effectiveTitleParts.value) {
+    return `${effectiveTitleParts.value.action} ${effectiveTitleParts.value.entityName}`
+  }
+  return props.title
+})
+
+// Only show PageHeader breadcrumb if global breadcrumb feature is disabled
+const showBreadcrumb = computed(() => {
+  return props.breadcrumb?.length && !features.breadcrumb
+})
 </script>
 
 <template>
   <div class="page-header">
     <div class="page-header-content">
-      <Breadcrumb v-if="breadcrumb?.length" :items="breadcrumb" />
+      <Breadcrumb v-if="showBreadcrumb" :items="breadcrumb" />
       <div class="page-header-row">
         <div class="page-header-left">
           <div>
-            <h1 class="page-title">{{ title }}</h1>
+            <h1 class="page-title">
+              <template v-if="hasDecoratedTitle"><span class="entity-label">{{ effectiveTitleParts.entityLabel }}</span></template>
+              <span v-if="effectiveTitleParts" class="action-badge">{{ effectiveTitleParts.action }} {{ effectiveTitleParts.entityName }}</span>
+              <template v-if="!effectiveTitleParts">{{ title }}</template>
+            </h1>
             <p v-if="subtitle" class="page-subtitle">{{ subtitle }}</p>
           </div>
           <slot name="subtitle" ></slot>
@@ -72,4 +118,24 @@ defineProps({
   font-size: 0.875rem;
   color: var(--p-text-secondary);
 }
+
+/* Action badge (Edit User / Create Role) - small grey badge */
+.action-badge {
+  display: inline-block;
+  font-size: 0.5em;
+  font-weight: 600;
+  background: var(--p-surface-200);
+  color: var(--p-surface-600);
+  padding: 0.25em 0.6em;
+  border-radius: 4px;
+  margin-left: 0.5em;
+  vertical-align: middle;
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+}
+
+/* Entity label in title - main focus */
+.entity-label {
+  font-weight: 600;
+}
 </style>

package/src/components/layout/PageLayout.vue

@@ -21,8 +21,9 @@ import Button from 'primevue/button'
 import { useBreadcrumb } from '../../composables/useBreadcrumb'
 
 const props = defineProps({
-  // Header
-  title: { type: String, required: true },
+  // Header - use title OR titleParts (for decorated entity label)
+  title: { type: String, default: null },
+  titleParts: { type: Object, default: null },  // { action, entityName, entityLabel }
   subtitle: { type: String, default: null },
   headerActions: { type: Array, default: () => [] },
   breadcrumb: { type: Array, default: null },  // Override auto breadcrumb
@@ -52,7 +53,7 @@ function resolveLabel(label) {
 
 <template>
   <div>
-    <PageHeader :title="title" :breadcrumb="props.breadcrumb || breadcrumbItems">
+    <PageHeader :title="title" :title-parts="titleParts" :breadcrumb="props.breadcrumb || breadcrumbItems">
       <template #subtitle>
         <slot name="subtitle">
           <span v-if="subtitle" class="page-subtitle">{{ subtitle }}</span>

package/src/composables/index.js

@@ -17,3 +17,4 @@ export { useAuth } from './useAuth'
 export { useNavigation } from './useNavigation'
 export { useStatus } from './useStatus'
 export { useUnsavedChangesGuard } from './useUnsavedChangesGuard'
+export { useManager } from './useManager'

package/src/composables/useBareForm.js

@@ -1,4 +1,4 @@
-import { ref, computed, provide, onUnmounted } from 'vue'
+import { ref, computed, provide, inject, onUnmounted } from 'vue'
 import { useRoute, useRouter } from 'vue-router'
 import { useToast } from 'primevue/usetoast'
 import { useDirtyState } from './useDirtyState'
@@ -20,6 +20,9 @@ import { registerGuardDialog, unregisterGuardDialog } from './useGuardStore'
  *   } = useBareForm({
  *     getState: () => ({ form: form.value }),
  *     routePrefix: 'agents',    // for cancel() navigation
+ *     entityName: 'Agent',      // for auto-title (optional, or use 'entity' for auto-lookup)
+ *     labelField: 'name',       // field to use as entity label (optional)
+ *     entity: 'agents',         // EntityManager name for auto metadata (optional)
  *     guard: true,              // enable unsaved changes modal
  *     onGuardSave: () => save() // optional save callback for guard modal
  *   })
@@ -32,20 +35,25 @@ import { registerGuardDialog, unregisterGuardDialog } from './useGuardStore'
  * - Common computed (isEdit, entityId)
  * - Navigation helpers (cancel)
  * - Access to router, route, toast
+ * - Auto page title via provide (for PageHeader)
  *
  * @param {Object} options
  * @param {Function} options.getState - Function returning current form state for comparison
  * @param {string} options.routePrefix - Route name for cancel navigation (default: '')
+ * @param {string} options.entityName - Display name for entity (default: from manager or derived from routePrefix)
+ * @param {string|Function} options.labelField - Field name or function to extract entity label (default: from manager or 'name')
+ * @param {string|Ref|Object} options.entity - EntityManager name (string) for auto metadata, OR entity data (Ref/Object) for breadcrumb
  * @param {boolean} options.guard - Enable unsaved changes guard (default: true)
  * @param {Function} options.onGuardSave - Callback for save button in guard modal
  * @param {Function} options.getId - Custom function to extract entity ID from route (optional)
- * @param {Ref|Object} options.entity - Entity data for dynamic breadcrumb labels (optional)
  * @param {Function} options.breadcrumbLabel - Callback (entity) => string for custom breadcrumb label (optional)
  */
 export function useBareForm(options = {}) {
   const {
     getState,
     routePrefix = '',
+    entityName = null,
+    labelField = null,
     guard = true,
     onGuardSave = null,
     getId = null,
@@ -57,6 +65,19 @@ export function useBareForm(options = {}) {
     throw new Error('useBareForm requires a getState function')
   }
 
+  // Try to get EntityManager metadata if entity is a string
+  let manager = null
+  if (typeof entity === 'string') {
+    const orchestrator = inject('qdadmOrchestrator', null)
+    if (orchestrator) {
+      try {
+        manager = orchestrator.get(entity)
+      } catch {
+        // Manager not found, continue without it
+      }
+    }
+  }
+
   // Router, route, toast - common dependencies
   const router = useRouter()
   const route = useRoute()
@@ -88,8 +109,53 @@ export function useBareForm(options = {}) {
   provide('isFieldDirty', isFieldDirty)
   provide('dirtyFields', dirtyFields)
 
+  // Resolve entityName: explicit > manager > derived from routePrefix
+  const derivedEntityName = routePrefix
+    ? routePrefix.charAt(0).toUpperCase() + routePrefix.slice(1).replace(/s$/, '')
+    : null
+  const effectiveEntityName = entityName || manager?.label || derivedEntityName
+
+  // Resolve labelField: explicit > manager > default 'name'
+  const effectiveLabelField = labelField || manager?.labelField || 'name'
+
+  // Provide entity context for child components (e.g., SeverityTag auto-discovery)
+  if (routePrefix) {
+    const entityNameForProvider = routePrefix.endsWith('s') ? routePrefix : routePrefix + 's'
+    provide('mainEntity', entityNameForProvider)
+  } else if (typeof entity === 'string') {
+    provide('mainEntity', entity)
+  }
+
+  // Auto page title parts for PageHeader
+  const getEntityLabel = () => {
+    const state = getState()
+    const formData = state.form || state
+    if (!formData) return null
+    // Use manager.getEntityLabel if available, otherwise use effectiveLabelField
+    if (manager) {
+      return manager.getEntityLabel(formData)
+    }
+    if (typeof effectiveLabelField === 'function') {
+      return effectiveLabelField(formData)
+    }
+    return formData[effectiveLabelField] || null
+  }
+
+  const pageTitleParts = computed(() => ({
+    action: isEdit.value ? 'Edit' : 'Create',
+    entityName: effectiveEntityName,
+    entityLabel: isEdit.value ? getEntityLabel() : null
+  }))
+
+  // Provide title parts for automatic PageHeader consumption
+  if (effectiveEntityName) {
+    provide('qdadmPageTitleParts', pageTitleParts)
+  }
+
   // Breadcrumb (auto-generated from route path, with optional entity for dynamic labels)
-  const { breadcrumbItems } = useBreadcrumb({ entity, getEntityLabel: breadcrumbLabel })
+  // Only pass entity to breadcrumb if it's actual entity data (not a string manager name)
+  const breadcrumbEntity = typeof entity === 'string' ? null : entity
+  const { breadcrumbItems } = useBreadcrumb({ entity: breadcrumbEntity, getEntityLabel: breadcrumbLabel })
 
   // Unsaved changes guard
   let guardDialog = null
@@ -117,6 +183,9 @@ export function useBareForm(options = {}) {
     route,
     toast,
 
+    // Manager (if resolved from entity string)
+    manager,
+
     // State
     loading,
     saving,
@@ -138,6 +207,9 @@ export function useBareForm(options = {}) {
     breadcrumb: breadcrumbItems,
 
     // Guard dialog (for UnsavedChangesDialog component)
-    guardDialog
+    guardDialog,
+
+    // Title helpers
+    pageTitleParts
   }
 }