# Components library

Add Elementor clipboard JSON to `elementor/classic/` or `elementor/atomic/`,
then add its metadata to `catalog.json`. Each entry has `id`, `title`,
`description`, `editor` (`classic` or `atomic`), `tier` (`free` or `pro`),
`preview`, `preview_url`, and, for available sections, `file`. Set `preview_url`
to the live design preview link, or `"#"` until that link is available. This URL
is used by the card's Preview Design action; it defaults to `"#"` when omitted.
Pro providers inherit the existing card's preview image and demo URL when their
entry omits `preview` and `preview_url`, respectively. The inherited image URL
continues to point to the Free plugin's assets.
File and preview image paths are
relative to this directory. IDs are stable and unique across both editors.

Payloads use `{"type":"elementor","siteurl":"","elements":[...]}`.
The library sets the current REST root at copy time. Include nested elements,
local styles, and Atomic schema versions. Use portable content without
site-specific media IDs, global styles, or component references. Atomic heading,
paragraph, and button text is adapted to the installed widget schemas. Atomic
sections may include Classic widgets and containers; their settings are preserved,
while Atomic descendants still receive schema normalization. Use `editor: "atomic"`
for mixed sections. Classic sections must contain only Classic elements.

The Free plugin owns all preview images and public catalog metadata, including
locked paid entries, but never their JSON files or file references. Add each new
Pro component's metadata, thumbnail, and public demo URL here first, with
`tier: "pro"` and no `file`. Store its image only in this plugin's `previews/`.

The Pro catalog supplies entries with the same IDs, editor formats, and
`tier: "pro"` to unlock those cards while its provider is active. Pro entries
keep `id`, `title`, `description`, `editor`, `tier`, and `file`; omit `preview`
to reuse the Free thumbnail without shipping an image copy. `preview_url` may
also be omitted to inherit the Free demo link. An entry without `preview` needs
a matching existing Pro card; unknown IDs and mismatched editors cannot inherit.
Paid JSON file paths remain relative to the Pro library's own directory.

Existing providers that explicitly supply a local `preview` remain supported.

A plugin can register its local library through:

```php
add_filter( 'wpaddons_component_libraries', function ( $libraries ) {
    $libraries['my-pro-library'] = array(
        'directory' => __DIR__ . '/assets/components',
        'url'       => plugins_url( 'assets/components/', __FILE__ ),
        'tier'      => 'pro',
    );
    return $libraries;
} );
```

Each library directory must contain `catalog.json`. Invalid catalogs are
ignored; invalid section files produce unavailable cards. Paths must remain
inside the registered directory. Catalog metadata is local content; it is not
a license service. Translate PHP UI strings using `advanced-animation`; JSON
sample content is intentionally editable by the user after pasting.