qdadm 0.13.0

package/CHANGELOG.md

@@ -0,0 +1,270 @@
+# Changelog
+
+All notable changes to qdadm will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.13.0] - 2025-12-21
+
+### Added
+- `EntityManager.getMany(ids)`: Batch fetch multiple entities by IDs
+  - Delegates to `storage.getMany(ids)` if available
+  - Falls back to parallel `get()` calls
+- `EntityManager.canCreate()`: Permission check for creating entities
+- `EntityManager.canUpdate(entity?)`: Permission check for updating entities
+- `EntityManager.children`: Config for parent-child entity relationships
+- `BoolCell` component: Standardized tristate boolean display
+  - `true` → green check (`--p-green-500`)
+  - `false` → red cross (`--p-red-500`)
+  - `null/undefined` → empty
+- `LocalStorage.getMany(ids)`: Optimized batch fetch for localStorage adapter
+
+### Changed
+- **BREAKING**: Removed `canWrite()` - use `canCreate()` / `canUpdate()` instead
+- `addCreateAction()`: Uses `manager.canCreate()` for visibility
+- `addEditAction()`: Uses `manager.canUpdate(row)` for visibility
+
+### Demo
+- `read` field moved from `books` to `loans` entity
+- `BookForm`: Tabs in edit mode showing child entities (Loans)
+- `LoanList`: Bulk actions "Mark Read" / "Mark Unread"
+- `LoanForm`: Toggle for `read` field
+- Permission examples updated to use `canCreate()` / `canUpdate()`
+
+## [0.12.0] - 2025-12-21
+
+### Added
+- `useListPageBuilder.addFilter({ local_filter })`: Custom filter callback for local mode
+  - Specifies HOW to filter when in local mode (items < threshold)
+  - Example: `local_filter: (item, value) => value === 'active' ? !item.returned_at : true`
+  - Filters with `local_filter` are **not sent to manager** (virtual fields)
+  - `local_filter: false` = manager only, skip in local mode
+- `useListPageBuilder.setSearch({ local_search })`: Custom search callback for local mode
+  - Specifies HOW to search when in local mode
+  - Example: `local_search: (item, query) => booksMap[item.book_id]?.title.includes(query)`
+  - `local_search: false` = manager only, skip in local mode
+- `EntityManager.localFilterThreshold`: Per-entity threshold for auto local filtering
+  - Priority: config `autoFilterThreshold` > `manager.localFilterThreshold` > default (100)
+
+### Changed
+- **BREAKING**: Renamed `filterMode: 'api'` → `filterMode: 'manager'` (clearer intent)
+- **Demo**: `LoanList` uses `local_filter` for virtual `status` filter
+- **Demo**: `LoanList` uses `local_search` for book title lookup
+
+### Documentation
+- **The threshold decides everything**:
+  - `items >= threshold` → **manager mode**: delegate ALL filtering to EntityManager
+  - `items < threshold` → **local mode**: filter client-side
+- **Modes**:
+  - `filterMode: 'manager'`: Always delegate to EntityManager
+  - `filterMode: 'local'`: Always filter client-side
+  - `filterMode: 'auto'` (default): Switch based on threshold
+- **Behavior Matrix**:
+  | Type                        | Mode `manager`  | Mode `local`                |
+  |-----------------------------|-----------------|-----------------------------|
+  | Filter standard             | Manager handles | `item[field] === value`     |
+  | Filter + `local_filter`     | Manager handles | `local_filter(item, value)` |
+  | Filter + `local_filter:false` | Manager handles | (skipped)                 |
+  | Search standard             | Manager handles | `field.includes(query)`     |
+  | Search + `local_search`     | Manager handles | `local_search(item, query)` |
+  | Search + `local_search:false` | Manager handles | (skipped)                 |
+- **Threshold Priority**: config > `manager.localFilterThreshold` > 100
+
+## [0.11.0] - 2025-12-20
+
+### Added
+- **Demo**: Permission-aware form fields pattern
+  - `LoanForm`: Non-admin users get `user_id` auto-set and field locked
+  - `LoansManager.create()`: Enforces `user_id` server-side for non-admin
+- **Demo**: Detailed comments on `useForm` return values (`loading`, `saving`, `dirty`, `isEdit`)
+
+### Changed
+- **Demo**: Simplified `onMounted` pattern replaces `watch` for form field initialization
+
+## [0.10.0] - 2025-12-20
+
+### Added
+- **Demo**: Complete permission patterns with documented examples
+  - `UsersManager`: Admin-only access (canRead/canWrite)
+  - `BooksManager`: Everyone edits, admin-only delete (canDelete)
+  - `LoansManager`: Ownership-based filtering (list override + row-level permissions)
+- **Demo**: Detailed JSDoc comments explaining all qdadm patterns
+- **Demo**: Fixture seeding system with JSON files
+
+### Changed
+- **Demo**: Login page shows all available demo accounts with role explanations
+
+## [0.9.0] - 2025-12-20
+
+### Added
+- `useListPageBuilder.props`: Computed object with all ListPage props - use with `v-bind="list.props.value"`
+- `useListPageBuilder.events`: Event handlers object - use with `v-on="list.events"`
+- `useListPageBuilder.hasBulkActions`: Auto-detects if bulk actions are available
+- Auto-selectable: Checkboxes shown only when bulk actions exist (no manual `selectable` prop needed)
+
+### Changed
+- ListPage template simplified from ~20 props/events to just `v-bind` + `v-on`
+
+## [0.8.0] - 2025-12-20
+
+### Added
+- `EntityManager.canDelete(entity?)`: Fine-grained delete permission check
+- `useListPageBuilder`: Standard actions now respect permissions:
+  - `addCreateAction()`: Hidden if `manager.canCreate()` returns false
+  - `addEditAction()`: Hidden per row if `manager.canUpdate(row)` returns false
+  - `addDeleteAction()`: Hidden per row if `manager.canDelete(row)` returns false
+  - `addBulkDeleteAction()`: Hidden if `manager.canDelete()` returns false
+
+## [0.7.0] - 2025-12-20
+
+### Added
+- `Kernel`: All-in-one bootstrap class - handles Vue app, Pinia, PrimeVue, router, auth guard, and qdadm
+  - Constructor is declarative (stores config only)
+  - `createApp()` does all initialization, returns Vue app for mount
+  - Allows tweaking `kernel.options` before `createApp()`, or adding plugins/directives before `mount()`
+  ```js
+  const kernel = new Kernel({
+    root: App,
+    modules: import.meta.glob('./modules/*/init.js', { eager: true }),
+    managers, authAdapter,
+    pages: { login, layout },
+    homeRoute: 'book',
+    app: { name: 'My App' },
+    primevue: { plugin: PrimeVue, theme: Aura }
+  })
+  kernel.createApp().mount('#app')
+  ```
+- `kernel.getRouter()`, `kernel.getApp()`, `kernel.getOrchestrator()` - access internals
+
+## [0.6.0] - 2025-12-20
+
+### Added
+- `registry.addRoutes(prefix, routes, { entity })`: Route-level entity binding for permission checks
+- `registry.addNavItem({ entity })`: Nav item entity binding for permission checks
+- **Auto Route Guard**: Plugin adds `beforeEach` guard that redirects to `/` if `manager.canRead()` returns false
+- **Auto Nav Filtering**: `useNavigation` filters items and hides empty sections based on `manager.canRead()`
+
+## [0.5.0] - 2025-12-20
+
+### Added
+- `useGuardStore`: Shared reactive store for automatic UnsavedChangesDialog rendering
+- `AppLayout`: Automatically renders UnsavedChangesDialog when a form is active (no code needed in forms)
+- `EntityManager.canRead(entity?)`: Permission check for reading (general or specific entity)
+- `EntityManager.canWrite(entity?)`: Permission check for writing (general or specific entity)
+
+### Changed
+- `useBareForm`: Uses `registerGuardDialog`/`unregisterGuardDialog` from store instead of provide/inject
+- `UnsavedChangesDialog`: Refactored to use `SimpleDialog` internally
+- `PageLayout`: Removed `guardDialog` prop (dialog is now automatic via AppLayout)
+
+### Removed
+- `features.scopes`: Removed from plugin config - permission logic belongs in EntityManager
+- `useAuth.hasScope()`: Replaced by `EntityManager.canRead()`/`canWrite()` pattern
+
+### Fixed
+- `useDirtyState`: Fixed timing issue where `takeSnapshot()` used `nextTick()` causing navigation to be blocked after save
+
+## [0.4.0] - 2025-12-20
+
+### Added
+- `EntityManager.getEntityLabel(entity)`: Method to get display label, handles both string field and callback
+- `EntityManager.labelField`: Can now be a string (field name) or callback function `(entity) => string`
+- `PageLayout`: `manager` prop - derives labelField automatically from EntityManager
+
+### Changed
+- `PageLayout`: Uses `manager.getEntityLabel()` instead of manual field access
+- `useBreadcrumb`: Shows entity label in breadcrumb (replaces ID segment), keeps action labels (Edit/Create/View)
+
+## [0.3.1] - 2025-12-20
+
+### Added
+- `AppLayout`: "powered by qdadm" footer with version display
+- `assets/logo.svg`: Hexagon logo with "QD" in two-tone blue
+- `features.poweredBy`: Option to hide "powered by" footer (default: true)
+
+### Fixed
+- `AppLayout`: Vue Flow and full-height components now render correctly (flex layout)
+- `AppLayout`: Use `<RouterView />` fallback when no slot content provided
+
+### Changed
+- `AppLayout`: Sidebar width uses CSS variable `var(--fad-sidebar-width, 15rem)` instead of hardcoded `250px`
+- `tokens.css`: Layout tokens now use `rem` units (`--fad-sidebar-width`, `--fad-header-height`, `--fad-content-max-width`)
+- `main.css`: Removed ~130 lines of duplicated styles (sidebar, nav, login, user-info) - now only in AppLayout scoped CSS
+
+## [0.3.0] - 2025-12-20
+
+### Added
+- `AppLayout` component with auto-nav from module registry
+- `useNavigation` composable for navigation state management
+- `useStatus` composable for generic status/option loading
+- `setSectionOrder()` to configure navigation section order
+- `initModules()` accepts external module imports and core nav items
+
+### Changed
+- Module registry is now fully configurable (no hardcoded imports)
+- Navigation auto-builds from module declarations (registry.addNavItem)
+- Branding comes from bootstrap config (createQdadm app option)
+- Dashboard now uses qdadm AppLayout instead of local implementation
+
+### Removed
+- Hardcoded import.meta.glob in moduleRegistry
+- Hardcoded sectionOrder in moduleRegistry
+
+## [0.2.0] - 2025-12-20
+
+### Added
+- README.md with quick start guide
+- TODO.md for planned features
+- docs/FRAMEWORK.md moved from dashboard
+
+### Changed
+- Successfully integrated with Faketual dashboard
+- All 60+ dashboard modules migrated to use qdadm imports
+- Validated build and runtime functionality
+
+### Fixed
+- Component import paths (PageHeader, CardsGrid, ListPage)
+- useJsonSyntax import paths in editor components
+- Theme CSS import path in styles/index.css
+
+## [0.1.0] - 2025-12-20
+
+### Added
+- Initial extraction from Faketual dashboard
+- `createQdadm` plugin for Vue 3 bootstrap
+- **Adapters**:
+  - `ApiAdapter` interface for CRUD operations
+  - `AuthAdapter` interface for authentication (optional)
+- **Composables**:
+  - `useForm` - Form state management with validation
+  - `useListPageBuilder` - Paginated list with filters and actions
+  - `useBareForm` - Minimal form without routing
+  - `useBreadcrumb` - Breadcrumb builder
+  - `useDirtyState` - Track unsaved changes
+  - `useEntityTitle` - Dynamic page titles
+  - `useJsonSyntax` - JSON validation helpers
+  - `usePageBuilder` - Generic page builder
+  - `useSubEditor` - Sub-component for complex forms
+  - `useTabSync` - Sync tabs with URL
+  - `useUnsavedChangesGuard` - Block navigation if dirty
+  - `useAuth` - Authentication access
+  - `useApp` - App branding access
+- **Components**:
+  - Layout: `PageLayout`, `PageHeader`, `Breadcrumb`
+  - Forms: `FormField`, `FormActions`, `FormTabs`, `FormTab`
+  - Lists: `ListPage`, `ActionButtons`, `ActionColumn`, `FilterBar`
+  - Editors: `KeyValueEditor`, `LanguageEditor`, `ScopeEditor`, `VanillaJsonEditor`, `JsonEditorFoldable`, `JsonStructuredField`, `JsonViewer`
+  - Dialogs: `SimpleDialog`, `MultiStepDialog`, `BulkStatusDialog`, `UnsavedChangesDialog`
+  - Display: `CardsGrid`, `RichCardsGrid`, `CopyableId`, `EmptyState`, `IntensityBar`
+  - Auth: `LoginPage`, `AuthGuard`, `ScopeGuard`
+- **Module System**:
+  - `moduleRegistry` for auto-discovery of modules
+  - Route registration with path prefix
+  - Navigation item registration
+  - Route family for active state detection
+- **Configuration**:
+  - `app` config for branding (name, logo, version, theme)
+  - `features` toggles (auth, scopes)
+  - `builtinModules` for users/roles
+  - `endpoints` configuration

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 quazardous
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,166 @@
+# qdadm
+
+Vue 3 framework for building admin dashboards with PrimeVue.
+
+## Features
+
+- **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.
+
+## Installation
+
+```bash
+npm install qdadm
+```
+
+## Quick Start with Kernel
+
+```js
+import { Kernel, EntityManager, LocalStorage } from 'qdadm'
+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')
+  },
+  homeRoute: 'book',
+  app: { name: 'My App', version: '1.0.0' },
+  primevue: { plugin: PrimeVue, theme: Aura }
+})
+
+kernel.createApp().mount('#app')
+```
+
+## Manual Bootstrap (without Kernel)
+
+```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 }))
+```
+
+## Module Structure
+
+```
+modules/
+└── books/
+    ├── init.js          # Route & nav registration
+    └── pages/
+        ├── BookList.vue
+        └── BookForm.vue
+```
+
+**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-'])
+}
+```
+
+## EntityManager Permissions
+
+```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'
+  }
+}
+```
+
+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
+- vue-router ^4.0.0
+- primevue ^4.0.0
+- pinia ^2.0.0
+- vanilla-jsoneditor ^0.23.0
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "qdadm",
+  "version": "0.13.0",
+  "description": "Vue 3 framework for admin dashboards with PrimeVue",
+  "author": "quazardous",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/quazardous/qdadm.git"
+  },
+  "homepage": "https://github.com/quazardous/qdadm#readme",
+  "bugs": {
+    "url": "https://github.com/quazardous/qdadm/issues"
+  },
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./composables": "./src/composables/index.js",
+    "./components": "./src/components/index.js",
+    "./module": "./src/module/index.js",
+    "./utils": "./src/utils/index.js",
+    "./styles": "./src/styles/index.css"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "vue": "^3.3.0",
+    "vue-router": "^4.0.0",
+    "primevue": "^4.0.0",
+    "pinia": "^2.0.0",
+    "vanilla-jsoneditor": "^0.23.0"
+  },
+  "keywords": [
+    "vue",
+    "vue3",
+    "admin",
+    "dashboard",
+    "framework",
+    "primevue",
+    "crud",
+    "entity-manager"
+  ]
+}

package/src/assets/logo.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" width="100" height="100">
+  <polygon points="50,5 93,27.5 93,72.5 50,95 7,72.5 7,27.5" fill="#1E3A8A"/>
+  <text x="48" y="50" text-anchor="middle" dominant-baseline="central" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif" font-size="58" font-weight="800" letter-spacing="-4">
+    <tspan fill="#60A5FA">Q</tspan><tspan fill="#93C5FD">D</tspan>
+  </text>
+</svg>

package/src/components/BoolCell.vue

@@ -0,0 +1,28 @@
+<script setup>
+/**
+ * BoolCell - Standardized boolean display for list columns
+ *
+ * Tristate display:
+ * - true: green check
+ * - false: red cross
+ * - null/undefined: empty
+ *
+ * Usage:
+ * <Column field="read" header="Read">
+ *   <template #body="{ data }">
+ *     <BoolCell :value="data.read" />
+ *   </template>
+ * </Column>
+ */
+defineProps({
+  value: {
+    type: Boolean,
+    default: null
+  }
+})
+</script>
+
+<template>
+  <i v-if="value === true" class="pi pi-check" style="color: var(--p-green-500)" />
+  <i v-else-if="value === false" class="pi pi-times" style="color: var(--p-red-500)" />
+</template>

package/src/components/dialogs/BulkStatusDialog.vue

@@ -0,0 +1,43 @@
+<script setup>
+import SimpleDialog from './SimpleDialog.vue'
+import Select from 'primevue/select'
+
+defineProps({
+  visible: Boolean,
+  title: { type: String, default: 'Change Status' },
+  options: { type: Array, required: true },
+  modelValue: [String, Number],
+  loading: Boolean,
+  selectionCount: { type: Number, default: 0 }
+})
+
+defineEmits(['update:visible', 'update:modelValue', '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>