@wix/babel-plugin-jsx-dynamic-data

A Babel plugin that automatically adds data attributes to JSX elements to help identify dynamic content, collection data bindings, and static array iterations. These attributes are used by the Picasso editor to understand which parts of the DOM are reactive and how they relate to underlying data sources.

Installation

npm install --save-dev @wix/babel-plugin-jsx-dynamic-data
# or
yarn add --dev @wix/babel-plugin-jsx-dynamic-data

Usage

Add the plugin to your Babel configuration:

// babel.config.js
module.exports = {
  plugins: ["@wix/babel-plugin-jsx-dynamic-data"],
};

Data Attributes Reference

Overview

The plugin adds three categories of data attributes:

| Category | Purpose | |----------|---------| | Dynamic Content | Identifies which element attributes have dynamic values | | Collection Data | Tracks data bindings to CMS collections | | Static Arrays | Identifies iterations over hardcoded arrays |

1. Dynamic Content Detection

data-dynamic

A space-separated list of attribute names or special values indicating which parts of the element are dynamic.

| Value | Meaning | |-------|---------| | text | The element's text content is fully dynamic | | text-composition | The element has both static text and dynamic expressions | | style | The style attribute contains dynamic values | | className | The className attribute is dynamic | | {attribute} | Any other attribute name (e.g., id, href, src) | | CSS properties | When Tailwind classes are conditionally applied, the mapped CSS properties are listed (e.g., background-color, padding) |

Example: Dynamic text content

// Input
<p>Hello, {name}!</p>

// Output
<p data-dynamic="text-composition">Hello, {name}!</p>

Example: Fully dynamic text

// Input
<span>{message}</span>

// Output
<span data-dynamic="text">{message}</span>

Example: Dynamic attributes

// Input
<a href={url} className={isActive ? "active" : "inactive"}>Link</a>

// Output
<a href={url} className={isActive ? "active" : "inactive"} data-dynamic="className href">Link</a>

Example: Tailwind class mapping

// Input
<div className={isLarge ? "p-8 bg-blue-500" : "p-4 bg-gray-500"}>Content</div>

// Output
<div className={isLarge ? "p-8 bg-blue-500" : "p-4 bg-gray-500"} data-dynamic="background-color padding">Content</div>

2. Collection Data Attributes

These attributes track data bindings to CMS collections (via BaseCrudService).

Attribute Summary

| Attribute | Purpose | Example Value | |-----------|---------|---------------| | data-collection-id | Identifies the source collection | "tasks", "employees" | | data-collection-reference | Lists expanded reference fields | "assignedemployees,topic" | | data-collection-item-id | Expression to access item's _id | {item?._id} | | data-collection-item-field | Field path being displayed | "title", "price.localPrice" | | data-collection-field-reference | Marks elements from reference fields | "true" |

data-collection-id

Identifies which CMS collection the data originates from. Added to container elements that iterate over collection data.

// Input
const tasksData = await BaseCrudService.getAll('tasks');
setTasks(tasksData.items);

return (
  <div>
    {tasks.map(task => (
      <div key={task._id}>{task.title}</div>
    ))}
  </div>
);

// Output - the container div gets marked
<div data-collection-id="tasks">
  {tasks.map(task => (
    <div key={task._id}>{task.title}</div>
  ))}
</div>

data-collection-reference

A comma-separated list of reference fields that were expanded when fetching the collection data. Added alongside data-collection-id.

// Input
const tasksData = await BaseCrudService.getAll('tasks', ['assignedemployees', 'topic']);

// Output
<div data-collection-id="tasks" data-collection-reference="assignedemployees,topic">

data-collection-item-id

An expression that accesses the current item's _id. Used to identify which specific collection item is being rendered.

// Input
<span>{destination.continent}</span>

// Output
<span 
  data-collection-item-field="continent" 
  data-collection-item-id={destination?._id}
  data-dynamic="text"
>
  {destination.continent}
</span>

data-collection-item-field

The field path (dot notation for nested fields) being displayed in this element.

// Simple field
<h3>{product.title}</h3>
// → data-collection-item-field="title"

// Nested field
<span>{product.price.localPrice}</span>
// → data-collection-item-field="price.localPrice"

data-collection-field-reference

Marks elements that display data from a reference field (a related collection). Set to "true".

// Input - task.topics is a reference field to the "topics" collection
{task.topics.map(topic => (
  <span key={topic._id}>{topic.name}</span>
))}

// Output
<span 
  key={topic._id} 
  data-collection-field-reference="true"
  data-dynamic="text"
>
  {topic.name}
</span>

Collection Attributes - Full Example

// Input
export default function TasksPage() {
  const [tasks, setTasks] = useState([]);

  useEffect(() => {
    async function load() {
      const data = await BaseCrudService.getAll('tasks', ['assignedemployees']);
      setTasks(data.items);
    }
    load();
  }, []);

  return (
    <div className="container">
      {tasks.map(task => (
        <div key={task._id}>
          <h3>{task.title}</h3>
          <div>
            {task.assignedemployees?.map(emp => (
              <span key={emp._id}>{emp.name}</span>
            ))}
          </div>
        </div>
      ))}
    </div>
  );
}

// Output
<div 
  className="container" 
  data-collection-id="tasks" 
  data-collection-reference="assignedemployees"
>
  {tasks.map(task => (
    <div 
      key={task._id} 
      data-collection-item-id={task?._id}
    >
      <h3 
        data-collection-item-field="title" 
        data-collection-item-id={task?._id}
        data-dynamic="text"
      >
        {task.title}
      </h3>
      <div>
        {task.assignedemployees?.map(emp => (
          <span 
            key={emp._id} 
            data-collection-field-reference="true"
            data-dynamic="text"
          >
            {emp.name}
          </span>
        ))}
      </div>
    </div>
  ))}
</div>

3. Static Array Attributes

These attributes are added when iterating over hardcoded/static arrays defined in the component.

Attribute Summary

| Attribute | Purpose | Example Value | |-----------|---------|---------------| | data-arr-index | Runtime index in the array | {__arrIdx__} or {index} | | data-arr-variable-name | Variable name of the array | "navigation", "menuItems" | | data-arr-field | Field path for text content | "name", "label" |

When are these added?

Static array attributes are added when:

1. The array is defined as a constant in the component (not from props or state)
2. The array contains only static values (strings, numbers, objects with static properties)
3. The array is referenced by a variable name (not inline)

data-arr-index

The runtime index of the current item. If the map callback doesn't have an index parameter, one is automatically added (__arrIdx__).

data-arr-variable-name

The variable name of the static array being iterated.

data-arr-field

The field path used in the text content of the element.

Static Array - Example

// Input
const Layout = () => {
  const navigation = [
    { name: 'Home', href: '/' },
    { name: 'Works', href: '/projects' },
    { name: 'Skills', href: '/skills' }
  ];

  return (
    <nav>
      {navigation.map((item) => (
        <a key={item.name} href={item.href}>
          {item.name}
        </a>
      ))}
    </nav>
  );
};

// Output
<nav>
  {navigation.map((item, __arrIdx__) => (
    <a 
      key={item.name} 
      href={item.href}
      data-arr-index={__arrIdx__}
      data-arr-variable-name="navigation"
      data-arr-field="name"
      data-dynamic="href text"
    >
      {item.name}
    </a>
  ))}
</nav>

When static array attributes are NOT added

// ❌ Inline array literal (no variable name)
{[{ name: 'Home' }, { name: 'About' }].map(item => (
  <a>{item.name}</a>
))}

// ❌ Dynamic array from props or state
const MyComponent = ({ items }) => (
  <div>{items.map(item => <span>{item.name}</span>)}</div>
);

Behavior Notes

1. Only primitive HTML elements are processed. Custom React components (capitalized names) are skipped, except for special allowed components like Image, Link, Badge.

2. Ignored attributes: key, event handlers (onClick, onChange, etc.), and motion-related attributes (initial, animate, transition) do not trigger data-dynamic.

3. Only exported components are processed to optimize performance.

4. The plugin traces data flow through:

   • Variable assignments
   • Array methods (.filter(), .sort(), .slice(), spread [...arr])
   • State setters (setItems(data.items))
   • Object destructuring (const { items } = await ...)

Quick Reference

┌─────────────────────────────────────────────────────────────────────────┐
│                        DATA ATTRIBUTES QUICK REFERENCE                  │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  DYNAMIC CONTENT                                                        │
│  ────────────────                                                       │
│  data-dynamic="text"              → fully dynamic text                  │
│  data-dynamic="text-composition"  → mix of static + dynamic text        │
│  data-dynamic="href src style"    → dynamic attributes (space-sep)      │
│                                                                         │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  COLLECTION DATA (CMS)                                                  │
│  ─────────────────────                                                  │
│  data-collection-id="tasks"           → source collection name          │
│  data-collection-reference="emp,tag"  → expanded reference fields       │
│  data-collection-item-id={x?._id}     → item identifier expression      │
│  data-collection-item-field="title"   → field path being displayed      │
│  data-collection-field-reference      → marks reference field elements  │
│                                                                         │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  STATIC ARRAYS                                                          │
│  ─────────────────                                                      │
│  data-arr-index={idx}              → runtime array index                │
│  data-arr-variable-name="nav"      → array variable name                │
│  data-arr-field="name"             → field used in text content         │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘