qiming/qiming-vite-plugin-design-mode/packages/client-vue/src/composables/README.md

Vue3 Design Mode Composables

Vue3 Composition API equivalents of the React design mode hooks.

Overview

This directory contains Vue3 composables that provide the same functionality as the React hooks in /src/client/. These composables enable design mode functionality in Vue3 applications.

Composables

1. useDesignMode.ts (912 lines)

Purpose: Global design mode state management and bridge communication.

Ported from: src/client/DesignModeContext.tsx (1,079 lines)

Key Features:

• Global state management using reactive() and provide/inject
• Bridge communication with parent window via postMessage
• Message handling for style/content updates
• Batch update support with debouncing
• Health check and connection monitoring

Usage:

import { createDesignMode, useDesignMode } from './composables';

// In root component
const designMode = createDesignMode({
  enabled: true,
  iframeMode: {
    enabled: true,
    enableSelection: true,
    enableDirectEdit: true,
  },
  batchUpdate: {
    enabled: true,
    debounceMs: 300,
  },
});

// In child components
const { 
  isDesignMode, 
  selectedElement, 
  toggleDesignMode,
  selectElement,
  modifyElementClass,
  updateElementContent 
} = useDesignMode();

Key Methods:

• toggleDesignMode() - Toggle design mode on/off
• selectElement(element) - Select an element for editing
• modifyElementClass(element, newClass) - Update element classes
• updateElementContent(element, newContent) - Update element text content
• batchUpdateElements(updates) - Batch multiple updates
• resetModifications() - Reload page to reset changes

2. useSelectionManager.ts (539 lines)

Purpose: Element selection and interaction handling.

Ported from: src/client/SelectionManager.tsx (597 lines)

Key Features:

• Click and hover event handling
• Element validation (must have source mapping + static-content/static-class)
• Visual highlighting with outline and shadow
• Keyboard shortcuts (Esc to clear, Ctrl/Cmd+A to select)
• Element info extraction with hierarchy
• Component root detection for library components

Usage:

import { useSelectionManager } from './composables';

const {
  selectedElement,
  hoverElement,
  selectElement,
  clearSelection,
  extractElementInfo,
  addSelectionListener,
} = useSelectionManager(document.body, {
  enableSelection: true,
  enableHover: true,
  selectionDelay: 0,
  excludeSelectors: ['script', 'style', 'meta'],
  includeOnlyElements: false,
});

// Listen to selection changes
const unsubscribe = addSelectionListener((element) => {
  if (element) {
    const info = extractElementInfo(element);
    console.log('Selected:', info);
  }
});

Key Methods:

• selectElement(element) - Select and highlight element
• clearSelection() - Clear current selection
• extractElementInfo(element) - Get detailed element information
• addSelectionListener(callback) - Subscribe to selection changes

3. useEditManager.ts (367 lines)

Purpose: Content editing with contentEditable mode.

Ported from: src/client/managers/EditManager.ts (365 lines)

Key Features:

• ContentEditable mode for inline text editing
• Real-time sync to related elements (list items with same element-id)
• Throttled notifications (300ms) during typing
• Enter saves, Escape cancels
• Click outside to save
• Automatic peer element synchronization

Usage:

import { useEditManager } from './composables';

const processUpdate = async (update: UpdateState) => {
  // Handle update logic
  return { success: true };
};

const {
  handleDirectEdit,
  editTextContent,
  updateContent,
  updateStyle,
  updateAttribute,
} = useEditManager(processUpdate, config);

// Double-click to edit
element.addEventListener('dblclick', () => {
  handleDirectEdit(element, 'content');
});

Key Methods:

• handleDirectEdit(element, type) - Trigger edit mode
• editTextContent(element) - Enable contentEditable editing
• updateContent(element, newValue) - Programmatic content update
• updateStyle(element, newClass) - Programmatic style update
• updateAttribute(element, name, value) - Update element attribute

4. useObserverManager.ts (98 lines)

Purpose: DOM mutation observation.

Ported from: src/client/managers/ObserverManager.ts (81 lines)

Key Features:

• MutationObserver setup for DOM changes
• Watches: childList, characterData, attributes (class, style)
• Skips elements with data-ignore-mutation attribute
• Callbacks for content/style edits and node additions

Usage:

import { useObserverManager } from './composables';

const { enable, disable, isEnabled } = useObserverManager(
  (target, type) => {
    console.log(`Edit detected: ${type} on`, target);
  },
  (node) => {
    console.log('Node added:', node);
  }
);

// Start observing
enable();

// Stop observing
disable();

Key Methods:

• enable() - Start observing DOM mutations
• disable() - Stop observing and disconnect

Key Differences from React Version

State Management

• React: useState, useCallback, useEffect
• Vue3: ref, reactive, computed, watch, onMounted, onBeforeUnmount

Context/Injection

• React: createContext, useContext, Provider
• Vue3: provide, inject, InjectionKey

Lifecycle

• React: useEffect with cleanup
• Vue3: onMounted, onBeforeUnmount

Reactivity

• React: Explicit state setters
• Vue3: Direct mutation of ref.value or reactive properties

Integration with Shared Code

All composables import shared utilities from /src/client-shared/:

• bridge.ts - PostMessage communication
• attributeNames.ts - Data attribute name resolution
• sourceInfo.ts - Source mapping extraction
• sourceInfoResolver.ts - Usage-site resolution
• elementUtils.ts - Element validation helpers

Type Safety

All composables are fully typed with TypeScript, importing types from:

• /src/types/messages.ts - Message type definitions
• /src/types/UpdateTypes.ts - Update operation types

Testing

To test these composables:

1. Import in a Vue3 component
2. Call createDesignMode() in the root component
3. Use useDesignMode() in child components
4. Verify bridge communication with parent window
5. Test element selection and editing

Future Enhancements

• Add Vue3-specific optimizations (e.g., shallowRef for large objects)
• Create Vue3 component wrappers for easier integration
• Add Pinia store integration option
• Implement Vue DevTools integration
• Add unit tests with Vitest