@incodiy/cavains

Enterprise-grade bidirectional interactive form-to-preview visual inspector and synchronized highlighter suite for React and Next.js by Incodiy.

Overview

cavains connects complex form inputs with live preview elements in real-time. When an editor hovers or focuses on an input field, the corresponding UI node on the preview canvas illuminates with a subtle glow ring and helper badge. Clicking an element on the preview smoothly scrolls the form directly to the associated input field (click-to-edit).

Key Features

• Decoupled Target-Registry: Zero hardcoded couplings between form schemas and preview components.
• Non-Destructive Highlights: Uses floating bounding overlays or zero-layout-shift absolute rings.
• Bidirectional Sync: Supports both Form $\rightarrow$ Preview inspection and Preview $\rightarrow$ Form reverse click-to-edit navigation.
• Zero-Boilerplate CavaForm Integration: Automatically binds with @incodiy/cavaform fields via schema keys.
• Framework & Styling Agnostic: Compatible with Tailwind CSS, CSS Modules, Radix UI, shadcn/ui, or plain JSX.

Installation

npm install @incodiy/cavains
# or
yarn add @incodiy/cavains
# or
pnpm add @incodiy/cavains

Quick Start

1. Wrap Your Form & Preview with CavaInsProvider

import { CavaInsProvider, InspectTrigger, InspectTarget } from "@incodiy/cavains";

export function CustomEditor() {
  return (
    <CavaInsProvider accentColor="#2563eb" enableClickToEdit showBadges>
      <div className="grid grid-cols-12 gap-6">
        {/* Left: Form Area */}
        <div className="col-span-5 space-y-4">
          <InspectTrigger id="banner.headline">
            <input
              type="text"
              placeholder="Enter Headline..."
              className="border p-2 rounded w-full"
            />
          </InspectTrigger>

          <InspectTrigger id="banner.cta">
            <input
              type="text"
              placeholder="Button Text..."
              className="border p-2 rounded w-full"
            />
          </InspectTrigger>
        </div>

        {/* Right: Live Preview Area */}
        <div className="col-span-7">
          <div className="p-6 border rounded-xl bg-white shadow-sm space-y-3">
            <InspectTarget id="banner.headline" label="Headline Title">
              <h1 className="text-2xl font-black">Main Headline</h1>
            </InspectTarget>

            <InspectTarget id="banner.cta" label="Action Button">
              <button className="px-4 py-2 bg-blue-600 text-white font-bold rounded-lg">
                Get Started
              </button>
            </InspectTarget>
          </div>
        </div>
      </div>
    </CavaInsProvider>
  );
}

CavaForm Interoperability

When using @incodiy/cavaform, you can wrap fields directly or use the withCavaIns adapter:

import { TextField } from "@incodiy/cavaform";
import { withCavaIns, InspectTrigger } from "@incodiy/cavains";

// Option A: Direct Wrapper
<InspectTrigger id="username">
  <TextField schema={{ name: "username", label: "Username" }} value={val} onChange={setVal} />
</InspectTrigger>

// Option B: Higher-Order Component
const InspectedTextField = withCavaIns(TextField);
<InspectedTextField schema={{ name: "username", label: "Username" }} value={val} onChange={setVal} />

API Reference

<CavaInsProvider />

• accentColor?: string — Primary highlight glow color (default: #2563eb).
• enableClickToEdit?: boolean — Enables reverse preview-to-form scrolling (default: true).
• showBadges?: boolean — Shows floating helper pills above active preview elements (default: true).
• pulseAnimation?: boolean — Enables subtle pulse animation on active elements (default: true).
• scrollOffset?: number — Header scroll offset in pixels (default: 90).

<InspectTrigger />

• id: string — Matching identifier string connecting trigger with target.
• children: ReactNode | ((props) => ReactNode) — Form input or render props function.

<InspectTarget />

• id: string — Matching identifier string connecting target with trigger.
• label?: string — Friendly label text shown on floating helper badge.
• color?: string — Custom highlight color overriding provider accent.
• disableClickToEdit?: boolean — Disables click-to-scroll for this specific target.

License

MIT © Incodiy Team