qdadm 0.13.0

package/src/composables/useSubEditor.js

@@ -0,0 +1,165 @@
+import { computed, inject } from 'vue'
+
+/**
+ * Composable for building sub-editor components that edit a portion of parent form data.
+ *
+ * Sub-editors receive data via v-model and emit updates, but don't handle persistence.
+ * The parent form (using useForm/useBareForm) handles loading, saving, and dirty tracking.
+ *
+ * Usage in sub-editor:
+ *   const props = defineProps({ modelValue: Object })
+ *   const emit = defineEmits(['update:modelValue'])
+ *
+ *   const { data, update, field } = useSubEditor(props, emit)
+ *
+ *   // Access data
+ *   data.value.someField
+ *
+ *   // Update single field
+ *   update('someField', newValue)
+ *
+ *   // Computed getter/setter for field
+ *   const myField = field('someField', defaultValue)
+ *   myField.value = 'new value' // auto-emits update
+ *
+ *   // Nested field access
+ *   const nested = field('config.subsection.value', 0)
+ *
+ * Features:
+ * - Simplified update pattern (no manual spread)
+ * - Computed fields with get/set for v-model binding
+ * - Nested path support (dot notation)
+ * - Default values
+ * - Optional dirty field indicator integration with parent
+ *
+ * @param {Object} props - Component props (must include modelValue)
+ * @param {Function} emit - Component emit function
+ * @param {Object} options - Additional options
+ * @param {*} options.defaultData - Default data structure if modelValue is empty
+ */
+export function useSubEditor(props, emit, options = {}) {
+  const { defaultData = {} } = options
+
+  // Computed reference to data (with default fallback)
+  const data = computed(() => props.modelValue ?? defaultData)
+
+  /**
+   * Get value at nested path
+   */
+  function getNestedValue(obj, path) {
+    if (!path.includes('.')) {
+      return obj?.[path]
+    }
+    return path.split('.').reduce((curr, key) => curr?.[key], obj)
+  }
+
+  /**
+   * Set value at nested path, returning new object
+   */
+  function setNestedValue(obj, path, value) {
+    if (!path.includes('.')) {
+      return { ...obj, [path]: value }
+    }
+
+    const keys = path.split('.')
+    const result = { ...obj }
+    let current = result
+
+    for (let i = 0; i < keys.length - 1; i++) {
+      const key = keys[i]
+      current[key] = { ...current[key] }
+      current = current[key]
+    }
+
+    current[keys[keys.length - 1]] = value
+    return result
+  }
+
+  /**
+   * Update a field and emit the new value
+   * @param {string} path - Field path (supports dot notation for nested)
+   * @param {*} value - New value
+   */
+  function update(path, value) {
+    const newData = setNestedValue(data.value, path, value)
+    emit('update:modelValue', newData)
+  }
+
+  /**
+   * Replace entire data object
+   * @param {Object} newData - Complete new data object
+   */
+  function replace(newData) {
+    emit('update:modelValue', newData)
+  }
+
+  /**
+   * Create a computed ref for a field with get/set
+   * Useful for v-model binding in template
+   *
+   * @param {string} path - Field path (supports dot notation)
+   * @param {*} defaultValue - Default value if field is undefined
+   * @returns {ComputedRef} Writable computed ref
+   */
+  function field(path, defaultValue = undefined) {
+    return computed({
+      get: () => {
+        const value = getNestedValue(data.value, path)
+        return value !== undefined ? value : defaultValue
+      },
+      set: (value) => update(path, value)
+    })
+  }
+
+  /**
+   * Create multiple field refs at once
+   * @param {Object} fields - { fieldName: defaultValue, ... }
+   * @returns {Object} { fieldName: computedRef, ... }
+   */
+  function fields(fieldDefs) {
+    const result = {}
+    for (const [path, defaultValue] of Object.entries(fieldDefs)) {
+      result[path] = field(path, defaultValue)
+    }
+    return result
+  }
+
+  /**
+   * Get value with default fallback (non-reactive, for one-time reads)
+   */
+  function get(path, defaultValue = undefined) {
+    const value = getNestedValue(data.value, path)
+    return value !== undefined ? value : defaultValue
+  }
+
+  // Try to inject field-level dirty tracking from parent (if available)
+  const parentIsFieldDirty = inject('isFieldDirty', null)
+
+  /**
+   * Check if a field is dirty (if parent provides tracking)
+   * This allows sub-editors to show field-level dirty indicators
+   */
+  function isFieldDirty(path) {
+    if (!parentIsFieldDirty) return false
+    // The parent tracks 'form.value.fieldName' or similar
+    // We need to prefix with the path the parent uses
+    return parentIsFieldDirty(path)
+  }
+
+  return {
+    // Data access
+    data,
+    get,
+
+    // Updates
+    update,
+    replace,
+
+    // Field helpers
+    field,
+    fields,
+
+    // Dirty tracking (from parent)
+    isFieldDirty
+  }
+}

package/src/composables/useTabSync.js

@@ -0,0 +1,110 @@
+/**
+ * useTabSync - Composable for tab navigation with URL hash sync
+ *
+ * Provides:
+ * - activeTab computed from URL hash
+ * - onTabChange handler to update URL
+ * - Support for conditional tabs (edit mode only)
+ * - Lazy loading trigger on tab activation
+ *
+ * Usage:
+ *   const { activeTab, onTabChange } = useTabSync({
+ *     validTabs: ['general', 'style', 'behavior', 'newsrooms'],
+ *     defaultTab: 'general',
+ *     restrictedTabs: { newsrooms: () => isEdit.value },
+ *     onTabActivate: { newsrooms: () => loadNewsroomData() }
+ *   })
+ */
+
+import { computed } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+
+/**
+ * @param {Object} options
+ * @param {string[]} options.validTabs - List of valid tab values
+ * @param {string} [options.defaultTab='general'] - Default tab when hash is invalid
+ * @param {Object.<string, Function>} [options.restrictedTabs={}] - Tab name -> condition function
+ * @param {Object.<string, Function>} [options.onTabActivate={}] - Tab name -> callback on first activation
+ */
+export function useTabSync(options = {}) {
+  const {
+    validTabs = ['general'],
+    defaultTab = 'general',
+    restrictedTabs = {},
+    onTabActivate = {}
+  } = options
+
+  const route = useRoute()
+  const router = useRouter()
+
+  // Track which tabs have been activated (for lazy loading)
+  const activatedTabs = new Set([defaultTab])
+
+  /**
+   * Active tab derived from URL hash
+   */
+  const activeTab = computed(() => {
+    const hash = route.hash?.replace('#', '')
+
+    if (hash && validTabs.includes(hash)) {
+      // Check if tab is restricted
+      const restriction = restrictedTabs[hash]
+      if (restriction && !restriction()) {
+        return defaultTab
+      }
+      return hash
+    }
+
+    return defaultTab
+  })
+
+  /**
+   * Handle tab change - update URL hash and trigger callbacks
+   * @param {string} newTab
+   */
+  function onTabChange(newTab) {
+    // Update URL hash
+    router.replace({ ...route, hash: `#${newTab}` })
+
+    // Trigger lazy load callback if first activation
+    if (!activatedTabs.has(newTab)) {
+      activatedTabs.add(newTab)
+      const callback = onTabActivate[newTab]
+      if (callback) {
+        callback()
+      }
+    }
+  }
+
+  /**
+   * Check if a tab should be visible
+   * @param {string} tabName
+   * @returns {boolean}
+   */
+  function isTabVisible(tabName) {
+    const restriction = restrictedTabs[tabName]
+    if (restriction) {
+      return restriction()
+    }
+    return true
+  }
+
+  /**
+   * Navigate to a specific tab programmatically
+   * @param {string} tabName
+   */
+  function goToTab(tabName) {
+    if (validTabs.includes(tabName) && isTabVisible(tabName)) {
+      onTabChange(tabName)
+    }
+  }
+
+  return {
+    activeTab,
+    onTabChange,
+    isTabVisible,
+    goToTab
+  }
+}
+
+export default useTabSync

package/src/composables/useUnsavedChangesGuard.js

@@ -0,0 +1,122 @@
+/**
+ * Composable for guarding against unsaved changes when leaving a page
+ *
+ * Usage:
+ * const { dirty, takeSnapshot, checkDirty } = useDirtyState(...)
+ * useUnsavedChangesGuard(dirty, {
+ *   onSave: () => handleSubmit(false),
+ *   message: 'You have unsaved changes.'
+ * })
+ */
+
+import { onBeforeUnmount, ref } from 'vue'
+import { onBeforeRouteLeave } from 'vue-router'
+
+/**
+ * Guard against leaving page with unsaved changes
+ *
+ * Shows a dialog with up to 3 options:
+ * - "Save & Leave" (if onSave provided) - saves then navigates
+ * - "Leave" - navigates without saving (discards changes)
+ * - "Stay" - cancels navigation
+ *
+ * @param {Ref<boolean>} dirty - Reactive dirty state
+ * @param {Object} options - Options
+ * @param {Function} options.onSave - Async function to save changes
+ * @param {string} options.message - Custom message (optional)
+ * @param {boolean} options.browserGuard - Show native browser dialog on tab close (default: false)
+ */
+export function useUnsavedChangesGuard(dirty, options = {}) {
+  const {
+    onSave = null,
+    message = 'You have unsaved changes that will be lost.',
+    browserGuard = false  // Disabled by default - use soft JS modal only
+  } = options
+
+  // State for custom dialog
+  const showDialog = ref(false)
+  const pendingNext = ref(null)
+  const saving = ref(false)
+
+  // Browser beforeunload event (for closing tab/window) - optional
+  function handleBeforeUnload(e) {
+    if (dirty.value) {
+      e.preventDefault()
+      e.returnValue = message
+      return message
+    }
+  }
+
+  // Add browser event listener only if browserGuard is enabled
+  if (browserGuard && typeof window !== 'undefined') {
+    window.addEventListener('beforeunload', handleBeforeUnload)
+  }
+
+  // Clean up on unmount
+  onBeforeUnmount(() => {
+    if (browserGuard && typeof window !== 'undefined') {
+      window.removeEventListener('beforeunload', handleBeforeUnload)
+    }
+  })
+
+  // Dialog actions
+  async function handleSaveAndLeave() {
+    if (!onSave || !pendingNext.value) return
+
+    saving.value = true
+    try {
+      await onSave()
+      showDialog.value = false
+      pendingNext.value()
+      pendingNext.value = null
+    } catch (e) {
+      console.error('Save failed:', e)
+      // Stay on page - don't close dialog, let user retry or choose Leave
+    } finally {
+      saving.value = false
+    }
+  }
+
+  function handleLeave() {
+    if (!pendingNext.value) return
+    showDialog.value = false
+    pendingNext.value()
+    pendingNext.value = null
+  }
+
+  function handleStay() {
+    showDialog.value = false
+    if (pendingNext.value) {
+      pendingNext.value(false)
+      pendingNext.value = null
+    }
+  }
+
+  // Vue Router navigation guard
+  onBeforeRouteLeave((to, from, next) => {
+    if (!dirty.value) {
+      next()
+      return
+    }
+
+    // Store the next callback and show dialog
+    pendingNext.value = next
+    showDialog.value = true
+  })
+
+  return {
+    dirty,
+    // Dialog state and handlers for custom dialog component
+    guardDialog: {
+      visible: showDialog,
+      saving,
+      message,
+      hasOnSave: !!onSave,
+      onSaveAndLeave: handleSaveAndLeave,
+      onLeave: handleLeave,
+      onStay: handleStay
+    }
+  }
+}
+
+export default useUnsavedChangesGuard