hydrogen-sanity/dist/visual-editing/index.d.ts

Sanity.io toolkit for Hydrogen

import {HistoryRefresh} from '@sanity/visual-editing'
import {OverlayComponentResolver} from '@sanity/visual-editing'
import {ReactElement} from 'react'
import {StegaConfig} from '@sanity/client'
import type {useRevalidator} from 'react-router'

/**
 * Live data synchronization component for real-time Studio updates.
 *
 * Enables real-time data updates and perspective changes between Sanity Studio
 * and your application. Only use when you have client-side loaders (`useQuery`).
 *
 * @param props.action - URL path for perspective change submissions
 * @param props.onConnect - Callback when Studio connection established
 * @param props.onDisconnect - Callback when Studio connection lost
 * @param props.filter - Stega filter for content encoding
 * @param props.studioUrl - Studio URL for stega configuration
 *
 * @example
 * ```tsx
 * // Basic live mode
 * <LiveMode />
 *
 * // With callbacks and custom action
 * <LiveMode
 *   action="/api/preview"
 *   onConnect={() => console.log('Connected')}
 *   onDisconnect={() => console.log('Disconnected')}
 * />
 * ```
 */
export declare function LiveMode(props: LiveModeProps): ReactElement

export declare interface LiveModeProps extends Omit<StegaConfig, 'enabled'> {
  /**
   * Fires when a connection is established to the Studio.
   */
  onConnect?: () => void
  /**
   * Fires when a connection to the Studio is lost.
   */
  onDisconnect?: () => void
}

/**
 * Visual editing overlays component for click-to-edit functionality.
 *
 * Provides interactive overlays that highlight content elements and enable
 * click-to-edit functionality. Does not include live data synchronization.
 *
 * @param props.components - Custom overlay components via OverlayComponentResolver
 * @param props.zIndex - CSS z-index for overlay positioning
 * @param props.refresh - Custom refresh logic for content changes
 *
 * @example
 * ```tsx
 * // Basic overlays
 * <Overlays />
 *
 * // With custom components
 * <Overlays components={customResolver} zIndex={1000} />
 * ```
 */
export declare function Overlays(props: OverlaysProps): ReactElement

export declare interface OverlaysProps {
  /**
   * Custom overlay components for visual editing.
   */
  components?: OverlayComponentResolver
  /**
   * The CSS z-index for visual editing overlays.
   */
  zIndex?: string | number
  /**
   * Custom refresh logic. Called when content changes.
   */
  refresh?: (
    payload: HistoryRefresh,
    refreshDefault: () => false | Promise<void>,
    revalidator: Revalidator,
  ) => false | Promise<void>
  /**
   * The action URL path used to submit perspective changes.
   */
  action?: string
}

export declare type Revalidator = ReturnType<typeof useRevalidator>

/**
 * Combined visual editing component that provides both overlays and automatic live mode detection.
 *
 * **Default Usage** (automatic detection):
 * ```tsx
 * <VisualEditing />  // Automatically enables live mode when `Query` components or `useQuery` hooks are present
 * ```
 *
 * **Individual Composition** (advanced usage):
 * ```tsx
 * <Overlays />
 * <LiveMode />  // When you need fine-grained control
 * ```
 *
 * Live mode automatically activates when `Query` components or `useQuery` hooks are detected,
 * providing zero-configuration setup for most users while offering advanced control when needed.
 *
 * @param props.action - The action URL path used to submit perspective changes
 * @param props.components - Custom overlay components for visual editing
 * @param props.zIndex - The CSS z-index for visual editing overlays
 * @param props.refresh - Custom refresh logic. Called when content changes
 * @param props.onConnect - Fires when a connection is established to the Studio
 * @param props.onDisconnect - Fires when a connection to the Studio is lost
 *
 * @see https://www.sanity.io/docs/introduction-to-visual-editing
 */
export declare function VisualEditing(props: VisualEditingProps): ReactElement

export declare interface VisualEditingProps extends Omit<StegaConfig, 'enabled'> {
  /**
   * The action URL path used to submit perspective changes.
   */
  action?: string
  /**
   * Custom overlay components for visual editing.
   */
  components?: OverlayComponentResolver
  /**
   * The CSS z-index for visual editing overlays.
   */
  zIndex?: string | number
  /**
   * Custom refresh logic. Called when content changes.
   */
  refresh?: (
    payload: HistoryRefresh,
    refreshDefault: () => false | Promise<void>,
    revalidator: Revalidator,
  ) => false | Promise<void>
  /**
   * Fires when a connection is established to the Studio.
   */
  onConnect?: () => void
  /**
   * Fires when a connection to the Studio is lost.
   */
  onDisconnect?: () => void
}

export {}