Setup

React / Next.js

1. Get the SuggestionElement

   Use the useSuggestionUtils() hook to obtain the SuggestionElement singleton.

   import { useSuggestionUtils } from '@veltdev/react';
   
   function YourComponent() {
     const suggestionElement = useSuggestionUtils();
   }
   
2. Tag DOM elements as suggestion targets

   Add the data-velt-suggestion-target attribute to any element you want to participate in suggestion mode.

   <input
     data-velt-suggestion-target="row.123.qty"
     type="number"
     defaultValue="5"
   />
   
3. Register suggestion targets

   Use useRegisterTarget() to get a registerTarget callback. For complex (non-primitive) targets, register a getter so the SDK can read the current value.

   import { useRegisterTarget } from '@veltdev/react';
   
   function EditableRow() {
     const { registerTarget } = useRegisterTarget();
   
     useEffect(() => {
       const unsubscribe = registerTarget({
         targetId: 'row.123',
         getter: () => ({
           qty: parseInt(document.getElementById('qty-input').value, 10),
           price: parseInt(document.getElementById('price-input').value, 10),
         }),
       });
       return () => unsubscribe();
     }, []);
   
     return (
       <>
         <input id="qty-input" data-velt-suggestion-target="row.123" type="number" defaultValue="5" />
         <input id="price-input" type="number" defaultValue="99" />
       </>
     );
   }
   
4. Enable suggestion mode

   Use useEnableSuggestionMode() to activate suggestion mode with optional lifecycle callbacks.

   import { useEnableSuggestionMode, useDisableSuggestionMode } from '@veltdev/react';
   
   function Toolbar() {
     const { enableSuggestionMode } = useEnableSuggestionMode();
     const { disableSuggestionMode } = useDisableSuggestionMode();
   
     const handleEnable = () => {
       enableSuggestionMode({
         onTargetEditStart: ({ targetId, oldValue, newValue, element }) => {
           // Informational. Reserved for future overrides.
         },
         onTargetEditCommit: ({ targetId, oldValue, newValue }) => {
           return {
             summary: `${targetId}: ${oldValue} → ${newValue}`,
             metadata: { source: 'inline-edit' },
           };
         },
       });
     };
   
     return (
       <>
         <button onClick={handleEnable}>Enable Suggestion Mode</button>
         <button onClick={() => disableSuggestionMode()}>Disable</button>
       </>
     );
   }
   
5. Listen to suggestion events

   Use useSuggestionEventCallback() to reactively subscribe to suggestion lifecycle events.

   import { useSuggestionEventCallback } from '@veltdev/react';
   import { useEffect } from 'react';
   
   function SuggestionHandler() {
     const approved = useSuggestionEventCallback('suggestionApproved');
     const rejected = useSuggestionEventCallback('suggestionRejected');
   
     useEffect(() => {
       if (approved?.suggestion) {
         // Apply approved.suggestion.newValue to your app state.
       }
     }, [approved]);
   
     useEffect(() => {
       if (rejected?.suggestion) {
         console.log('Rejected:', rejected.suggestion);
       }
     }, [rejected]);
   
     return null;
   }
   

Other Frameworks

1. Get the SuggestionElement

   Call Velt.getSuggestionElement() to obtain the SuggestionElement singleton.

   const suggestionElement = Velt.getSuggestionElement();
   
2. Tag DOM elements as suggestion targets

   Add the data-velt-suggestion-target attribute to any element you want to participate in suggestion mode.

   <input
     data-velt-suggestion-target="row.123.qty"
     type="number"
     value="5">
   
3. Register suggestion targets

   Call registerTarget() to associate a getter with a target ID for complex value reads.

   suggestionElement.registerTarget({
     targetId: 'row.123',
     getter: () => ({
       qty: parseInt(document.getElementById('qty-input').value, 10),
       price: parseInt(document.getElementById('price-input').value, 10),
     }),
   });
   
4. Enable suggestion mode

   Call enableSuggestionMode() with optional lifecycle callbacks.

   suggestionElement.enableSuggestionMode({
     onTargetEditStart: ({ targetId, oldValue, newValue, element }) => {
       // Informational. Reserved for future overrides.
     },
     onTargetEditCommit: ({ targetId, oldValue, newValue }) => {
       return {
         summary: `${targetId}: ${oldValue} → ${newValue}`,
         metadata: { source: 'inline-edit' },
       };
     },
   });
   
5. Listen to suggestion events

   Subscribe to suggestion lifecycle events using suggestionElement.on().

   suggestionElement.on('suggestionApproved').subscribe(({ suggestion }) => {
     // Apply suggestion.newValue to your app state here.
   });
   
   suggestionElement.on('suggestionRejected').subscribe(({ suggestion }) => {
     console.log('Rejected:', suggestion);
   });
   

React / Next.js

import {
  useSuggestionUtils,
  useRegisterTarget,
  useEnableSuggestionMode,
  useDisableSuggestionMode,
  useSuggestionModeState,
  useSuggestionEventCallback,
} from '@veltdev/react';
import { useEffect } from 'react';

function EditableRow() {
  const { registerTarget } = useRegisterTarget();

  useEffect(() => {
    const unsubscribe = registerTarget({
      targetId: 'row.123',
      getter: () => ({
        qty: parseInt(document.getElementById('qty-input')?.value ?? '0', 10),
      }),
    });
    return () => unsubscribe();
  }, []);

  const approved = useSuggestionEventCallback('suggestionApproved');
  useEffect(() => {
    if (approved?.suggestion) {
      // Apply approved.suggestion.newValue to your app state.
    }
  }, [approved]);

  return (
    <input
      id="qty-input"
      data-velt-suggestion-target="row.123"
      type="number"
      defaultValue="5"
    />
  );
}

function Toolbar() {
  const { enableSuggestionMode } = useEnableSuggestionMode();
  const { disableSuggestionMode } = useDisableSuggestionMode();
  const suggestionMode = useSuggestionModeState();

  return (
    <button onClick={() => suggestionMode ? disableSuggestionMode() : enableSuggestionMode()}>
      {suggestionMode ? 'Disable' : 'Enable'} Suggestion Mode
    </button>
  );
}