@quazardous/qdadm 2.11.0 → 2.13.0

package/README.md

@@ -2,23 +2,15 @@
 
 **Vue 3 admin framework. PrimeVue. Zero boilerplate.**
 
-Quick start: [README](https://github.com/quazardous/qdadm/blob/main/README.md) (5 min tutorial)
-
-Concepts & patterns: [QDADM_CREDO](https://github.com/quazardous/qdadm/blob/main/packages/qdadm/QDADM_CREDO.md)
-
-Changelog: [CHANGELOG](https://github.com/quazardous/qdadm/blob/main/CHANGELOG.md)
-
 ## Installation
 
 ```bash
 npm install @quazardous/qdadm primevue @primeuix/themes primeicons vue-router pinia
 ```
 
-qdadm ships raw TS/Vue sources, so Vite needs a small config assist to keep
-PrimeVue as a single module instance in dev. One line:
-
 ```ts
-// vite.config.ts
+// vite.config.ts — the plugin wires the resolver/optimizer settings
+// qdadm's raw-source packaging needs (npm and file:/workspace installs)
 import { qdadmVitePlugin } from '@quazardous/qdadm/vite'
 
 export default defineConfig({
@@ -26,135 +18,17 @@ export default defineConfig({
 })
 ```
 
-(It applies `resolve.dedupe` + the `optimizeDeps` exclude/include set — see
-the plugin's JSDoc for details. Without it, dev boots to a blank page with
-`Error: No PrimeVue Toast provided!`.)
-
-## Exports
-
-```js
-// Core
-import { Kernel, EntityManager } from '@quazardous/qdadm'
-
-// Storage backends
-import { MockApiStorage, ApiStorage, SdkStorage } from '@quazardous/qdadm'
-
-// Auth
-import { SessionAuthAdapter, LocalStorageSessionAuthAdapter } from '@quazardous/qdadm'
-
-// Security (permissions, roles)
-import { SecurityChecker, PermissionMatcher, PermissionRegistry } from '@quazardous/qdadm/security'
-import { PersistableRoleProvider, createLocalStorageRolesProvider } from '@quazardous/qdadm/security'
-
-// Composables
-import { useBareForm, useListPage } from '@quazardous/qdadm/composables'
-
-// Components
-import { ListPage, PageLayout, AppLayout, FormField, FormActions } from '@quazardous/qdadm/components'
-
-// Module system
-import { KernelContext } from '@quazardous/qdadm/module'
-
-// Styles
-import '@quazardous/qdadm/styles'
-```
-
-## ctx.crud() - Route Helper
-
-Register CRUD routes + navigation in one call:
-
-```js
-class BooksModule extends Module {
-  async connect(ctx) {
-    ctx.entity('books', { ... })
-
-    // Full CRUD with single form
-    ctx.crud('books', {
-      list: () => import('./pages/BookList.vue'),
-      form: () => import('./pages/BookForm.vue')  // create + edit
-    }, {
-      nav: { section: 'Library', icon: 'pi pi-book' }
-    })
-
-    // List only (read-only entity)
-    ctx.crud('settings', {
-      list: () => import('./pages/SettingsPage.vue')
-    }, { nav: { section: 'Config', icon: 'pi pi-cog' } })
-  }
-}
-```
-
-Auto-generates: routes, route family, nav item. Use `ctx.routes()` for custom pages.
-
-## SdkStorage
-
-Adapter for generated SDK clients (hey-api, openapi-generator, etc.):
-
-```js
-import { SdkStorage } from '@quazardous/qdadm'
-
-const storage = new SdkStorage({
-  sdk,
-  methods: {
-    list: 'getApiBooks',
-    get: 'getApiBooksById',
-    create: 'postApiBooks',
-    update: 'patchApiBooksById',
-    delete: 'deleteApiBooksById'
-  }
-})
-```
-
-Options: `transformRequest`, `transformResponse`, `responseFormat`, `clientSidePagination`.
-
 ## Documentation
 
-| Doc | Purpose |
-|-----|---------|
-| [QDADM_CREDO](https://github.com/quazardous/qdadm/blob/main/packages/qdadm/QDADM_CREDO.md) | Philosophy, patterns, concepts |
-| [Page compositions](https://github.com/quazardous/qdadm/blob/main/docs/page-compositions.md) | **Start here** — which composition for which need |
-| [CRUD Pages](https://github.com/quazardous/qdadm/blob/main/docs/crud.md) | List / form / show / child pages reference |
-| [Navigation](https://github.com/quazardous/qdadm/blob/main/docs/navigation.md) | Breadcrumb, sibling navlinks, View↔Edit toggle |
-| [Architecture](https://github.com/quazardous/qdadm/blob/main/docs/architecture.md) | PAC pattern, layers |
-| [Extension](https://github.com/quazardous/qdadm/blob/main/docs/extension.md) | Decorators, bundles, multi-storage |
-| [Hooks](https://github.com/quazardous/qdadm/blob/main/docs/hooks.md) | Alter / invoke registry |
-| [Signals](https://github.com/quazardous/qdadm/blob/main/docs/signals.md) | Event bus, SSE bridge |
-| [Zones](https://github.com/quazardous/qdadm/blob/main/docs/zones.md) | Extensible UI blocks |
-| [Security](https://github.com/quazardous/qdadm/blob/main/docs/security.md) | Permissions, roles |
-| [i18n](https://github.com/quazardous/qdadm/blob/main/docs/i18n.md) | Messages, providers, strategies |
-| [Codegen](https://github.com/quazardous/qdadm/blob/main/docs/gen.md) | Generate managers (OpenAPI / manual) |
-| [Deferred](https://github.com/quazardous/qdadm/blob/main/docs/deferred.md) | Deferred values & warmup |
-| [AGENT_GUIDE](https://github.com/quazardous/qdadm/blob/main/docs/AGENT_GUIDE.md) | Quick index for AI agents |
-
-## Peer Dependencies
-
-- vue ^3.3.0
-- vue-router ^4.0.0
-- primevue ^4.0.0
-- pinia ^2.0.0
+Start with the **[step-by-step tutorial](https://github.com/quazardous/qdadm/blob/main/docs/tutorial-mini-admin.md)** — bootstrap, CRUD, auth, navigation, parent-child in ~310 lines.
 
-## Consuming via `file:` link from a sibling monorepo
+- [Full documentation](https://github.com/quazardous/qdadm/tree/main/docs)
+- [Concepts & patterns (CREDO)](https://github.com/quazardous/qdadm/blob/main/docs/QDADM_CREDO.md)
+- [Changelog](https://github.com/quazardous/qdadm/blob/main/CHANGELOG.md)
 
-If you install qdadm with a `file:../path/to/qdadm` link instead of from npm — typically during local development on qdadm itself, or before a release lands — pnpm/npm resolves the symlink into the qdadm-monorepo's hoisted `node_modules`. That can pull a *second* copy of `primevue` (and `vue`, `vue-router`, `@primeuix/themes`) into your host bundle even though qdadm itself only declares them as peers.
-
-Symptom: PrimeVue components render without their Aura preset tokens — component-level CSS variables (`--p-paginator-nav-button-width`, etc.) end up undefined, so paginator buttons collapse to 16×16, datatables lose padding, rounded corners disappear. Plugin singletons rely on a shared runtime registry; two instances split the registry in half.
-
-Fix in the host's bundler config — `dedupe` collapses duplicates back to a single resolved copy:
-
-```ts
-// vite.config.ts
-export default defineConfig({
-  resolve: {
-    dedupe: ['vue', 'vue-router', 'primevue', '@primeuix/themes'],
-  },
-})
-```
-
-This is the canonical Vite/Webpack pattern for Vue plugin singletons. The `file:` link can stay in place — useful for hot-reload during qdadm development — and the dedupe ensures only one instance of each peer ends up in the bundle.
-
-Installing qdadm from npm avoids the *duplicate-copy* trap (the published tarball ships no `node_modules/`, so peers resolve from the host) — but a related *split-pipeline* trap still applies in Vite dev: the host's `primevue` import gets pre-bundled into `.vite/deps` while qdadm's raw sources import `node_modules/primevue/` directly, which also yields two PrimeVue instances. `qdadmVitePlugin()` (see Installation above) handles both cases — dedupe for links, optimizeDeps exclude/include for the pre-bundle split.
+## Peer Dependencies
 
-One more caveat: qdadm ships TypeScript sources, so with a `file:` link your `vue-tsc` / lint / test counters measure qdadm's **working tree**, not a released version. Any local qdadm edit moves your numbers with zero change on your side — don't calibrate quality ratchets or CI thresholds against a linked checkout; pin them to the published package your CI actually installs.
+vue ^3.3 · vue-router ^4 || ^5 · primevue ^4 · pinia ^2 || ^3 || ^4
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quazardous/qdadm",
-  "version": "2.11.0",
+  "version": "2.13.0",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",
@@ -71,6 +71,9 @@
     },
     "vite": {
       "optional": true
+    },
+    "primevue": {
+      "optional": true
     }
   },
   "optionalDependencies": {

package/src/composables/useDirtyState.ts

@@ -59,6 +59,10 @@ export function useDirtyState<T extends FormState = FormState>(
   // initial side each time doubled the per-key work, and the old
   // JSON.parse(JSON.stringify(state)) deep clone tripled the snapshot cost.
   let initialFieldSnapshots: Map<string, string> | null = null
+  // Parsed deep copy of the initial form, kept for path-aware isFieldDirty
+  // (#1396). Built once per snapshot; the per-keystroke checkDirty path
+  // (#1194) never touches it.
+  let initialForm: Record<string, unknown> | null = null
   const ready = ref(false)
 
   /** Resolve the form object inside the state (common 'form'/'formData' patterns). */
@@ -76,6 +80,16 @@ export function useDirtyState<T extends FormState = FormState>(
     return s === undefined ? 'undefined' : s
   }
 
+  /** Resolve a dot path ('config.login') in an object, undefined-safe. */
+  function getByPath(obj: unknown, path: string): unknown {
+    let cur: unknown = obj
+    for (const seg of path.split('.')) {
+      if (cur === null || cur === undefined || typeof cur !== 'object') return undefined
+      cur = (cur as Record<string, unknown>)[seg]
+    }
+    return cur
+  }
+
   function getFormSnapshot(): string {
     return JSON.stringify(getState())
   }
@@ -96,6 +110,7 @@ export function useDirtyState<T extends FormState = FormState>(
         fieldSnapshots.set(key, stringifyField(form[key]))
       }
       initialFieldSnapshots = fieldSnapshots
+      initialForm = JSON.parse(JSON.stringify(form)) as Record<string, unknown>
       ready.value = true
     })
   }
@@ -126,7 +141,21 @@ export function useDirtyState<T extends FormState = FormState>(
   }
 
   function isFieldDirty(fieldName: string): boolean {
-    return dirtyFields.value.includes(fieldName)
+    // Dot-free names: exact historical behavior.
+    if (!fieldName.includes('.')) {
+      return dirtyFields.value.includes(fieldName)
+    }
+    // Path-aware (#1396): a sub-field can only be dirty if its ROOT key is —
+    // the pre-filter reuses the per-key work checkDirty already did, and
+    // reading dirtyFields keeps the same reactive trigger as flat names.
+    const root = fieldName.slice(0, fieldName.indexOf('.'))
+    if (!dirtyFields.value.includes(root)) return false
+    if (!initialForm) return false
+    const currentForm = resolveForm(getState())
+    return (
+      stringifyField(getByPath(currentForm, fieldName)) !==
+      stringifyField(getByPath(initialForm, fieldName))
+    )
   }
 
   function reset(): void {
@@ -134,6 +163,7 @@ export function useDirtyState<T extends FormState = FormState>(
     dirtyFields.value = []
     initialSnapshot.value = null
     initialFieldSnapshots = null
+    initialForm = null
     ready.value = false
   }
 

package/src/entity/storage/MockApiStorage.ts

@@ -13,6 +13,10 @@ export interface MockApiStorageOptions<T extends EntityRecord = EntityRecord> {
   generateId?: () => string
   initialData?: T[] | null
   authCheck?: (() => boolean) | null
+  /** Override the localStorage key (default `mockapi_${entityName}_data`).
+   *  Needed when several apps sharing an origin use the same entity names
+   *  (e.g. multiple demos on one GitHub Pages site) (#1382). */
+  storageKey?: string
 }
 
 /**
@@ -63,6 +67,7 @@ export class MockApiStorage<T extends EntityRecord = EntityRecord> extends IStor
       generateId = defaultGenerateId,
       initialData = null,
       authCheck = null,
+      storageKey = null,
     } = options
 
     if (!entityName) {
@@ -72,7 +77,7 @@ export class MockApiStorage<T extends EntityRecord = EntityRecord> extends IStor
     this.entityName = entityName
     this.idField = idField
     this.generateId = generateId
-    this._storageKey = `mockapi_${entityName}_data`
+    this._storageKey = storageKey || `mockapi_${entityName}_data`
     this._data = new Map()
     this._authCheck = authCheck
 

package/src/vite/qdadmPlugin.ts

@@ -53,6 +53,26 @@ export interface QdadmVitePluginOptions {
    * (vue, vue-router, primevue, pinia).
    */
   dedupe?: string[]
+  /**
+   * PrimeVue "flavor" (#1393): alias every `primevue/*` import to a
+   * compatible fork (e.g. OpenVue). qdadm officially maintains and tests
+   * `primevue@4` (MIT) only — a flavor keeping the v4 module layout/API is
+   * drop-in; divergences are the consumer's to absorb.
+   *
+   * ```ts
+   * qdadmVitePlugin({ primevue: { package: 'openvue' } })
+   * ```
+   */
+  primevue?: {
+    /** Package that replaces `primevue` (e.g. 'openvue'). */
+    package: string
+    /**
+     * Optional package replacing `@primeuix/themes` — only needed if the
+     * flavor ships its own themes fork (none does today; OpenVue keeps the
+     * MIT @primeuix/* versions).
+     */
+    themes?: string
+  }
 }
 
 export function qdadmVitePlugin(options: QdadmVitePluginOptions = {}): Plugin {
@@ -64,26 +84,52 @@ export function qdadmVitePlugin(options: QdadmVitePluginOptions = {}): Plugin {
       // Symlinked install (file:/workspace link)? Allow serving from the
       // link target, which typically lives outside the consumer's root.
       const fsAllow: string[] = []
+      let symlinked = false
       try {
         const pkgDir = path.join(root, 'node_modules', '@quazardous', 'qdadm')
         const real = fs.realpathSync(pkgDir)
         if (real !== pkgDir) {
+          symlinked = true
           fsAllow.push(searchForWorkspaceRoot(root), real)
         }
       } catch {
         // not installed under root node_modules (aliased/hoisted) — nothing to allow
       }
 
+      // Flavor aliasing (#1393): after the alias, no `primevue`/themes ids
+      // remain in the graph — dedupe/exclude lists must name the flavor.
+      const flavor = options.primevue ?? null
+      const widgetPkg = flavor?.package ?? 'primevue'
+      const themesPkg = flavor?.themes ?? '@primeuix/themes'
+      const alias = []
+      if (flavor) {
+        alias.push({ find: /^primevue(\/|$)/, replacement: `${flavor.package}$1` })
+        if (flavor.themes) {
+          alias.push({ find: /^@primeuix\/themes(\/|$)/, replacement: `${flavor.themes}$1` })
+        }
+      }
+
+      // With a flavor, the original packages may still be installed — keep
+      // them excluded too, or the optimizer pre-bundles a stray
+      // `primevue/*` id that bypassed the alias (split-instance again).
+      const widgetExcludes = flavor ? [widgetPkg, 'primevue'] : [widgetPkg]
+      const themesExcludes =
+        flavor?.themes ? [themesPkg, '@primeuix/themes'] : [themesPkg]
+
       return {
         resolve: {
-          dedupe: ['vue', 'vue-router', 'primevue', 'pinia', ...(options.dedupe ?? [])],
+          ...(alias.length > 0 ? { alias } : {}),
+          dedupe: ['vue', 'vue-router', widgetPkg, 'pinia', ...(options.dedupe ?? [])],
         },
         optimizeDeps: {
-          exclude: ['primevue', '@primeuix/themes', '@quazardous/qdadm'],
-          include: [
-            ...CJS_TRANSITIVES.map((dep) => `@quazardous/qdadm > ${dep}`),
-            ...CJS_TRANSITIVES,
-          ],
+          exclude: [...widgetExcludes, ...themesExcludes, '@quazardous/qdadm'],
+          // One form per install mode: the nested path resolves through a
+          // real node_modules chain (npm installs), the plain form through a
+          // symlink realpath — declaring the unused one logs a "Failed to
+          // resolve dependency" warning (skybot testbed, #1389).
+          include: symlinked
+            ? [...CJS_TRANSITIVES]
+            : CJS_TRANSITIVES.map((dep) => `@quazardous/qdadm > ${dep}`),
         },
         ...(fsAllow.length > 0 ? { server: { fs: { allow: fsAllow } } } : {}),
       }