qdadm 0.16.0 → 0.18.0

package/README.md

@@ -44,7 +44,7 @@ kernel.createApp().mount('#app')
 
 ```js
 // Main
-import { Kernel, createQdadm, EntityManager, ApiStorage, LocalStorage } from 'qdadm'
+import { Kernel, createQdadm, EntityManager, ApiStorage, LocalStorage, SdkStorage } from 'qdadm'
 
 // Composables
 import { useForm, useBareForm, useListPageBuilder } from 'qdadm/composables'
@@ -62,6 +62,158 @@ import { formatDate, truncate } from 'qdadm/utils'
 import 'qdadm/styles'
 ```
 
+## SdkStorage
+
+Adapter for generated SDK clients (hey-api, openapi-generator, etc.). Maps SDK methods to standard CRUD operations with optional transforms.
+
+### Basic Usage
+
+```js
+import { EntityManager, SdkStorage } from 'qdadm'
+import { Sdk } from './generated/sdk.gen.js'
+
+const sdk = new Sdk({ client: myClient })
+
+const storage = new SdkStorage({
+  sdk,
+  methods: {
+    list: 'getApiAdminTasks',
+    get: 'getApiAdminTasksById',
+    create: 'postApiAdminTasks',
+    update: 'patchApiAdminTasksById',
+    delete: 'deleteApiAdminTasksById'
+  }
+})
+
+const manager = new EntityManager({
+  name: 'tasks',
+  storage,
+  labelField: 'name'
+})
+```
+
+### Configuration Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `sdk` | object | SDK instance |
+| `getSdk` | function | Callback for lazy SDK loading |
+| `methods` | object | Map operations to SDK method names or callbacks |
+| `transformRequest` | function | Global request transform `(operation, params) => params` |
+| `transformResponse` | function | Global response transform `(operation, data) => data` |
+| `transforms` | object | Per-method transforms (override global) |
+| `responseFormat` | object | Configure response normalization |
+| `clientSidePagination` | boolean | Handle pagination locally (default: false) |
+
+### Method Mapping
+
+Methods can be strings (SDK method name) or callbacks for full control:
+
+```js
+methods: {
+  // String: calls sdk.getItems({ query: params })
+  list: 'getItems',
+
+  // Callback: full control over SDK invocation
+  get: async (sdk, id) => {
+    const result = await sdk.getItemById({ path: { id } })
+    return result.data
+  }
+}
+```
+
+### Transform Callbacks
+
+**Global transforms** apply to all operations:
+
+```js
+new SdkStorage({
+  sdk,
+  methods: { list: 'getItems', get: 'getItemById' },
+  transformRequest: (operation, params) => {
+    if (operation === 'list') {
+      return { query: params }
+    }
+    return params
+  },
+  transformResponse: (operation, response) => response.data
+})
+```
+
+**Per-method transforms** override global ones:
+
+```js
+new SdkStorage({
+  sdk,
+  methods: { list: 'getItems' },
+  transforms: {
+    list: {
+      request: (params) => ({ query: { ...params, active: true } }),
+      response: (data) => ({ items: data.results, total: data.count })
+    }
+  }
+})
+```
+
+### Response Format Normalization
+
+For APIs with non-standard response shapes, configure normalization before transforms:
+
+```js
+new SdkStorage({
+  sdk,
+  methods: { list: 'getItems' },
+  responseFormat: {
+    dataField: 'results',      // Field containing array (e.g., 'data', 'results')
+    totalField: 'count',       // Field for total count (null = compute from array)
+    itemsField: 'data.items'   // Nested path (takes precedence over dataField)
+  }
+})
+```
+
+### Client-Side Pagination
+
+For SDKs that return all items without server-side pagination:
+
+```js
+new SdkStorage({
+  sdk,
+  methods: { list: 'getAllItems' },
+  clientSidePagination: true  // Fetches all, paginates/sorts/filters in-memory
+})
+```
+
+### Real-World Example (hey-api SDK)
+
+```js
+import { Sdk } from '@/generated/sdk.gen.js'
+import { client } from '@/generated/client.gen.js'
+
+// Configure client
+client.setConfig({ baseUrl: '/api' })
+
+const sdk = new Sdk({ client })
+
+const taskStorage = new SdkStorage({
+  sdk,
+  methods: {
+    list: 'getApiAdminTasks',
+    get: 'getApiAdminTasksById',
+    create: 'postApiAdminTasks',
+    patch: 'patchApiAdminTasksById',
+    delete: 'deleteApiAdminTasksById'
+  },
+  transforms: {
+    list: {
+      response: (data) => ({
+        items: data.items.map(t => ({ ...t, statusLabel: t.status.toUpperCase() })),
+        total: data.total
+      })
+    }
+  }
+})
+```
+
 ## Peer Dependencies
 
 - vue ^3.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qdadm",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",
@@ -14,6 +14,10 @@
   },
   "type": "module",
   "main": "src/index.js",
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
   "exports": {
     ".": "./src/index.js",
     "./composables": "./src/composables/index.js",
@@ -27,6 +31,9 @@
     "README.md",
     "LICENSE"
   ],
+  "dependencies": {
+    "@quazardous/quarkernel": "^2.1.0"
+  },
   "peerDependencies": {
     "vue": "^3.3.0",
     "vue-router": "^4.0.0",
@@ -43,5 +50,11 @@
     "primevue",
     "crud",
     "entity-manager"
-  ]
+  ],
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^5.2.1",
+    "@vue/test-utils": "^2.4.6",
+    "jsdom": "^25.0.1",
+    "vitest": "^2.1.8"
+  }
 }

package/src/components/forms/FormField.vue

@@ -1,13 +1,17 @@
 <script setup>
 /**
- * FormField - Wrapper for form fields with automatic dirty state styling
+ * FormField - Wrapper for form fields with automatic dirty state and error display
  *
  * Usage:
  * <FormField name="username" label="Username *">
  *   <InputText v-model="form.username" />
  * </FormField>
  *
- * The parent form must provide isFieldDirty via useForm's provideFormContext()
+ * The parent form (useFormPageBuilder) provides:
+ * - isFieldDirty: function to check if field is dirty
+ * - getFieldError: function to get field error message
+ * - handleFieldBlur: function to trigger validation on blur
+ * - formSubmitted: ref indicating if form was submitted
  */
 import { inject, computed } from 'vue'
 
@@ -27,31 +31,63 @@ const props = defineProps({
   fullWidth: {
     type: Boolean,
     default: false
+  },
+  /** Override error message (useful for custom validation) */
+  error: {
+    type: String,
+    default: null
+  },
+  /** Show error only after form submission */
+  showErrorOnSubmit: {
+    type: Boolean,
+    default: false
   }
 })
 
-// Inject isFieldDirty from parent form (provided by useForm)
+// Inject from parent form (provided by useFormPageBuilder)
 const isFieldDirty = inject('isFieldDirty', () => false)
+const getFieldError = inject('getFieldError', () => null)
+const handleFieldBlur = inject('handleFieldBlur', () => {})
+const formSubmitted = inject('formSubmitted', { value: false })
 
 const isDirty = computed(() => isFieldDirty(props.name))
 
+// Get error from prop or from form validation
+const fieldError = computed(() => {
+  if (props.error) return props.error
+  return getFieldError(props.name)
+})
+
+// Show error if: form submitted OR field was touched (validated on blur)
+const showError = computed(() => {
+  if (!fieldError.value) return false
+  if (props.showErrorOnSubmit) return formSubmitted.value
+  return true
+})
+
 const fieldClasses = computed(() => [
   'form-field',
   {
-    'field-dirty': isDirty.value
+    'field-dirty': isDirty.value,
+    'field-invalid': showError.value
   }
 ])
 
 const fieldStyle = computed(() =>
   props.fullWidth ? { gridColumn: '1 / -1' } : {}
 )
+
+function onBlur() {
+  handleFieldBlur(props.name)
+}
 </script>
 
 <template>
   <div :class="fieldClasses" :style="fieldStyle">
     <label v-if="label" :for="name">{{ label }}</label>
-    <slot ></slot>
-    <small v-if="hint" class="field-hint">{{ hint }}</small>
+    <slot :onBlur="onBlur"></slot>
+    <small v-if="showError" class="field-error">{{ fieldError }}</small>
+    <small v-else-if="hint" class="field-hint">{{ hint }}</small>
   </div>
 </template>
 
@@ -61,4 +97,26 @@ const fieldStyle = computed(() =>
   margin-top: 0.25rem;
   display: block;
 }
+
+.field-error {
+  color: var(--p-red-500);
+  margin-top: 0.25rem;
+  display: block;
+}
+
+.field-invalid :deep(input),
+.field-invalid :deep(textarea),
+.field-invalid :deep(.p-inputtext),
+.field-invalid :deep(.p-select),
+.field-invalid :deep(.p-dropdown) {
+  border-color: var(--p-red-500);
+}
+
+.field-invalid :deep(input:focus),
+.field-invalid :deep(textarea:focus),
+.field-invalid :deep(.p-inputtext:focus),
+.field-invalid :deep(.p-select:focus),
+.field-invalid :deep(.p-dropdown:focus) {
+  box-shadow: 0 0 0 1px var(--p-red-500);
+}
 </style>

package/src/components/forms/FormPage.vue

@@ -0,0 +1,276 @@
+<script setup>
+/**
+ * FormPage - Unified form page component
+ *
+ * Renders a complete CRUD form page with:
+ * - PageHeader with title and action buttons
+ * - Loading and error states
+ * - Form content via slots
+ * - FormActions footer
+ * - UnsavedChangesDialog integration
+ *
+ * Props come from useFormPageBuilder composable:
+ *
+ * ```vue
+ * const form = useFormPageBuilder({ entity: 'books' })
+ * form.generateFields()
+ * form.addSaveAction()
+ *
+ * <FormPage v-bind="form.props" v-on="form.events">
+ *   <template #fields>
+ *     <FormField v-model="form.data.title" name="title" />
+ *   </template>
+ * </FormPage>
+ * ```
+ *
+ * Slots:
+ * - #nav: PageNav for breadcrumb customization
+ * - #toolbar: Custom toolbar actions (between header and form)
+ * - #header-actions: Custom header action buttons
+ * - #fields: Form fields content (required)
+ * - #footer: Custom footer (replaces FormActions if provided)
+ * - #error: Custom error display
+ * - #loading: Custom loading display
+ */
+import { computed } from 'vue'
+import PageHeader from '../layout/PageHeader.vue'
+import FormActions from './FormActions.vue'
+import UnsavedChangesDialog from '../dialogs/UnsavedChangesDialog.vue'
+import Card from 'primevue/card'
+import Button from 'primevue/button'
+import Message from 'primevue/message'
+
+const props = defineProps({
+  // Mode
+  isEdit: { type: Boolean, default: false },
+  mode: { type: String, default: 'create' },
+
+  // State
+  loading: { type: Boolean, default: false },
+  saving: { type: Boolean, default: false },
+  dirty: { type: Boolean, default: false },
+
+  // Title (use title OR titleParts)
+  title: { type: String, default: null },
+  titleParts: { type: Object, default: null },
+
+  // Fields (for auto-rendering - optional, can use #fields slot instead)
+  fields: { type: Array, default: () => [] },
+
+  // Actions (from builder.actions)
+  actions: { type: Array, default: () => [] },
+
+  // Validation state
+  errors: { type: Object, default: () => ({}) },
+  hasErrors: { type: Boolean, default: false },
+  errorSummary: { type: Array, default: null },
+  submitted: { type: Boolean, default: false },
+
+  // Guard dialog (from useUnsavedChangesGuard)
+  guardDialog: { type: Object, default: null },
+
+  // Error for fetch failures (separate from validation errors)
+  fetchError: { type: [String, Object], default: null },
+
+  // UI options
+  showFormActions: { type: Boolean, default: true },
+  showSaveAndClose: { type: Boolean, default: true },
+  cardWrapper: { type: Boolean, default: true }
+})
+
+const emit = defineEmits(['save', 'saveAndClose', 'cancel', 'delete'])
+
+// Computed: has any action buttons to show
+const hasActions = computed(() => props.actions.length > 0)
+
+// Get action by name
+function getAction(name) {
+  return props.actions.find(a => a.name === name)
+}
+
+// Check if action exists and is visible
+function hasAction(name) {
+  return props.actions.some(a => a.name === name)
+}
+
+// Extract specific actions for FormActions component
+const saveAction = computed(() => getAction('save'))
+const deleteAction = computed(() => getAction('delete'))
+const cancelAction = computed(() => getAction('cancel'))
+
+// Header actions: all actions except save, delete, cancel (those go in footer)
+const headerActions = computed(() =>
+  props.actions.filter(a => !['save', 'delete', 'cancel'].includes(a.name))
+)
+
+// Get error message from fetchError
+const fetchErrorMessage = computed(() => {
+  if (!props.fetchError) return null
+  if (typeof props.fetchError === 'string') return props.fetchError
+  return props.fetchError.message || props.fetchError.detail || 'Failed to load entity'
+})
+
+// Guard dialog handlers
+function onGuardSaveAndLeave() {
+  if (props.guardDialog?.onSave) {
+    props.guardDialog.onSave()
+  }
+}
+
+function onGuardLeave() {
+  if (props.guardDialog?.onLeave) {
+    props.guardDialog.onLeave()
+  }
+}
+
+function onGuardStay() {
+  if (props.guardDialog?.onStay) {
+    props.guardDialog.onStay()
+  }
+}
+</script>
+
+<template>
+  <div class="form-page">
+    <!-- Nav slot for PageNav (child routes) -->
+    <slot name="nav" />
+
+    <PageHeader :title="title" :title-parts="titleParts">
+      <template #actions>
+        <slot name="header-actions" />
+        <!-- Header actions from builder (excludes save/delete/cancel) -->
+        <Button
+          v-for="action in headerActions"
+          :key="action.name"
+          :label="action.label"
+          :icon="action.icon"
+          :severity="action.severity"
+          :loading="action.isLoading"
+          :disabled="action.isDisabled"
+          @click="action.onClick"
+        />
+      </template>
+    </PageHeader>
+
+    <!-- Toolbar slot (between header and form) -->
+    <slot name="toolbar" />
+
+    <!-- Loading State -->
+    <template v-if="loading">
+      <slot name="loading">
+        <div class="loading-state">
+          <i class="pi pi-spin pi-spinner" style="font-size: 2rem"></i>
+        </div>
+      </slot>
+    </template>
+
+    <!-- Error State (fetch error) -->
+    <template v-else-if="fetchError">
+      <slot name="error" :error="fetchError">
+        <Message severity="error" :closable="false" class="form-error-message">
+          {{ fetchErrorMessage }}
+        </Message>
+      </slot>
+    </template>
+
+    <!-- Form Content -->
+    <template v-else>
+      <!-- Validation Error Summary -->
+      <Message
+        v-if="errorSummary && errorSummary.length > 0"
+        severity="warn"
+        :closable="false"
+        class="validation-summary"
+      >
+        <ul class="validation-errors">
+          <li v-for="error in errorSummary" :key="error.field">
+            <strong>{{ error.label }}:</strong> {{ error.message }}
+          </li>
+        </ul>
+      </Message>
+
+      <!-- Card wrapper or direct content -->
+      <Card v-if="cardWrapper">
+        <template #content>
+          <slot name="fields" />
+
+          <!-- Form Actions (in footer) -->
+          <template v-if="showFormActions">
+            <slot name="footer">
+              <FormActions
+                :isEdit="isEdit"
+                :saving="saving"
+                :dirty="dirty"
+                :showSaveAndClose="showSaveAndClose"
+                @save="emit('save')"
+                @saveAndClose="emit('saveAndClose')"
+                @cancel="emit('cancel')"
+              />
+            </slot>
+          </template>
+        </template>
+      </Card>
+
+      <template v-else>
+        <slot name="fields" />
+
+        <!-- Form Actions (in footer) -->
+        <template v-if="showFormActions">
+          <slot name="footer">
+            <FormActions
+              :isEdit="isEdit"
+              :saving="saving"
+              :dirty="dirty"
+              :showSaveAndClose="showSaveAndClose"
+              @save="emit('save')"
+              @saveAndClose="emit('saveAndClose')"
+              @cancel="emit('cancel')"
+            />
+          </slot>
+        </template>
+      </template>
+    </template>
+
+    <!-- Unsaved Changes Dialog -->
+    <UnsavedChangesDialog
+      v-if="guardDialog"
+      v-model:visible="guardDialog.visible"
+      :saving="saving"
+      :hasOnSave="!!guardDialog.onSave"
+      @saveAndLeave="onGuardSaveAndLeave"
+      @leave="onGuardLeave"
+      @stay="onGuardStay"
+    />
+  </div>
+</template>
+
+<style scoped>
+.form-page {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+.loading-state {
+  display: flex;
+  justify-content: center;
+  padding: 3rem;
+}
+
+.form-error-message {
+  margin: 1rem 0;
+}
+
+.validation-summary {
+  margin-bottom: 1rem;
+}
+
+.validation-errors {
+  margin: 0;
+  padding-left: 1.5rem;
+}
+
+.validation-errors li {
+  margin: 0.25rem 0;
+}
+</style>

package/src/components/index.js

@@ -4,12 +4,23 @@
 
 // Layout
 export { default as AppLayout } from './layout/AppLayout.vue'
+export { default as BaseLayout } from './layout/BaseLayout.vue'
 export { default as PageLayout } from './layout/PageLayout.vue'
 export { default as PageHeader } from './layout/PageHeader.vue'
 export { default as Breadcrumb } from './layout/Breadcrumb.vue'
 export { default as PageNav } from './layout/PageNav.vue'
+export { default as Zone } from './layout/Zone.vue'
+
+// Default zone components
+export { default as DefaultHeader } from './layout/defaults/DefaultHeader.vue'
+export { default as DefaultMenu } from './layout/defaults/DefaultMenu.vue'
+export { default as DefaultFooter } from './layout/defaults/DefaultFooter.vue'
+export { default as DefaultUserInfo } from './layout/defaults/DefaultUserInfo.vue'
+export { default as DefaultBreadcrumb } from './layout/defaults/DefaultBreadcrumb.vue'
+export { default as DefaultToaster } from './layout/defaults/DefaultToaster.vue'
 
 // Forms
+export { default as FormPage } from './forms/FormPage.vue'
 export { default as FormField } from './forms/FormField.vue'
 export { default as FormActions } from './forms/FormActions.vue'
 export { default as FormTabs } from './forms/FormTabs.vue'