qdadm 0.13.0 → 0.14.2

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.2",
   "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

@@ -1,5 +1,5 @@
 <script setup>
-import { ref, onMounted, watch, inject } from 'vue'
+import { ref, computed, onMounted, watch, inject } from 'vue'
 import AutoComplete from 'primevue/autocomplete'
 import Select from 'primevue/select'
 import Button from 'primevue/button'
@@ -13,29 +13,40 @@ const props = defineProps({
     type: Boolean,
     default: false
   },
-  // Scope configuration
+  // Scope configuration (can be overridden globally via provide('scopeConfig', {...}))
   scopeEndpoint: {
     type: String,
-    default: '/reference/scopes' // Endpoint to load scope definition from API
+    default: null
   },
   scopePrefix: {
     type: String,
-    default: 'faketual' // Prefix for scope strings (e.g., "faketual.resource:action")
+    default: null
   },
   // Default resources/actions if API not available
   defaultResources: {
     type: Array,
-    default: () => ['api', 'users', 'roles', 'apikeys']
+    default: null
   },
   defaultActions: {
     type: Array,
-    default: () => ['read', 'write', 'grant']
+    default: null
   }
 })
 
 // Get API adapter (optional)
 const api = inject('apiAdapter', null)
 
+// Get global scope config (optional) - allows app-level configuration
+const globalScopeConfig = inject('scopeConfig', {})
+
+// Computed config with priority: props > globalConfig > defaults
+const config = computed(() => ({
+  endpoint: props.scopeEndpoint ?? globalScopeConfig.endpoint ?? '/reference/scopes',
+  prefix: props.scopePrefix ?? globalScopeConfig.prefix ?? 'app',
+  resources: props.defaultResources ?? globalScopeConfig.resources ?? ['api', 'users', 'roles', 'apikeys'],
+  actions: props.defaultActions ?? globalScopeConfig.actions ?? ['read', 'write', 'grant']
+}))
+
 const emit = defineEmits(['update:modelValue'])
 
 // Scope structure from API
@@ -57,8 +68,6 @@ const allResources = computed(() => ['*', ...scopeDefinition.value.resources])
 // All actions with access prefix
 const allActions = computed(() => ['access', ...scopeDefinition.value.actions])
 
-import { computed } from 'vue'
-
 /**
  * Search resources for autocomplete
  */
@@ -79,7 +88,7 @@ function searchResources(event) {
 function parseScope(scope) {
   if (!scope) return { resource: '', action: '' }
   // prefix.resource:action
-  const regex = new RegExp(`^${props.scopePrefix}\\.([^:]+):(.+)$`)
+  const regex = new RegExp(`^${config.value.prefix}\\.([^:]+):(.+)$`)
   const match = scope.match(regex)
   if (match) {
     return { resource: match[1], action: match[2] }
@@ -92,7 +101,7 @@ function parseScope(scope) {
  */
 function buildScope(resource, action) {
   if (!resource || !action) return ''
-  return `${props.scopePrefix}.${resource}:${action}`
+  return `${config.value.prefix}.${resource}:${action}`
 }
 
 // Initialize from modelValue
@@ -154,22 +163,22 @@ async function loadScopeDefinition() {
     if (!api) {
       // No API adapter, use defaults
       scopeDefinition.value = {
-        resources: [...props.defaultResources],
-        actions: [...props.defaultActions],
+        resources: [...config.value.resources],
+        actions: [...config.value.actions],
       }
       return
     }
 
-    const data = await api.request('GET', props.scopeEndpoint)
+    const data = await api.request('GET', config.value.endpoint)
     scopeDefinition.value = {
-      resources: data.resources || [...props.defaultResources],
-      actions: data.actions || [...props.defaultActions],
+      resources: data.resources || [...config.value.resources],
+      actions: data.actions || [...config.value.actions],
     }
   } catch (error) {
     console.error('[ScopeEditor] Failed to load scope definition:', error)
     scopeDefinition.value = {
-      resources: [...props.defaultResources],
-      actions: [...props.defaultActions],
+      resources: [...config.value.resources],
+      actions: [...config.value.actions],
     }
   } finally {
     loading.value = false

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'