@brizy/core/README.md

Brizy Core to register your own component into Brizy Builder

# Brizy Builder Core
![Logo](https://www.brizy.io/account/application/default/themes/themefuse/public/img/logo-account.png)

**Brizy Builder Core** package allow to Register your own third party components into Brizy Builder.


[![Stable Release](https://img.shields.io/npm/v/@brizy/core)](https://npm.im/@brizy/core)

## Limitations
This package can only be used in the Brizy Builder context. It cannot be used in other applications.

## Installation

Install my-project with npm

```bash
  npm install @brizy/core
```

## Usage/Examples

Import `Brizy` core, and then you can register your own component

```javascript
import { Brizy } from "@brizy/core";
import { ToolbarProps } from "../types/toolbars";
import { getItems as getSidebarItems } from "./sidebar";
import "./style.scss";
import { getItems as getToolbarItems } from "./toolbar";

export function MySuperComponent(props: Props): JSX.Element {
  return (
    <div className="componentToolbar">
      {/*... your component code...*/}
      
    </div>
  );
}

Brizy.registerComponent(MySuperComponent, {
  id: "MySupercomponentId",
  //... other props
  options: (props: ToolbarProps) => [
    {
      selector: ".componentToolbar",    // open toolbar when you click on element with this selector
      toolbar: getToolbarItems(props),  // toolbar description...
      sidebar: getSidebarItems(props)   // sidebar desription...
    }
  ]
});
```


## Core Interface
```typescript
Class Brizy{
    static registerComponent<T>(
        component:ComponentType, // this is React Component Type
        componentConfig: ComponentData<T>
  ){}
}

export interface ComponentData<T> {
  id: string;
  title: string;
  category?: string;
  keywords?: Array<string>;
  mode?: EditorMode;
  preview?: Preview;
  icon?: string;
  options?: (props: ValueGetter) => ToolbarConfig[];
}
```
... Other types you can find in `dist/types`


## Registering Plugins

Besides components, `@brizy/core` can register **editor plugins** — runtime add-ons
that contribute UI into named editor slots (left-sidebar tabs, floating panels),
extend toolbars/sidebars through filters, and listen to editor events. Call
`Brizy.registerPlugin` from your plugin's entry bundle; it writes the plugin onto
the editor config so the builder registers it during initialization.

```javascript
import { Brizy } from "@brizy/core";
import type { EditorPlugin } from "@brizy/core";

function createMyPlugin(): EditorPlugin {
  return {
    id: "myPlugin",
    name: "My Plugin",
    register(api) {
      const removePanel = api.slots.add("floatingPanel", {
        id: "myPlugin",
        component: MyPanel
      });

      const removeFilter = api.filters.add(
        "toolbar.clickOutsideExceptions",
        (exceptions) =>
          Array.isArray(exceptions) ? [...exceptions, ".my-plugin"] : exceptions
      );

      // Optional cleanup — the editor calls it when it unmounts.
      return () => {
        removePanel();
        removeFilter();
      };
    }
  };
}

Brizy.registerPlugin(createMyPlugin());
```

> The entry bundle must run **before** the editor bootstrap reads the config (for
> example, loaded via a `<script>` ahead of the editor bundle). Calling
> `registerPlugin` after the editor has already initialized has no effect.

### Plugin types

```typescript
interface EditorPlugin<Api = PluginAPI> {
  id: string;
  name: string;
  register(api: Api): void | (() => void); // optionally returns a cleanup fn
}

type PluginSlotName = "leftSidebar.drawer" | "leftSidebar.tab" | "floatingPanel";

interface PluginAPI {
  slots: {
    add(slot: PluginSlotName, contribution: PluginSlotContribution): () => void;
  };
  filters: {
    add(
      name: string,
      cb: (...args: unknown[]) => unknown,
      priority?: number
    ): () => void;
  };
  events: {
    on(event: string, handler: (...args: unknown[]) => void): () => void;
    emit(event: string, data?: unknown): void;
  };
  t: (key: string) => string;
  // ...plus `store`, `toolServer`, and optional page/project getters
}
```


#  ImageUtility Class

This package also exports a helpful utility class called ImageUtility, designed to simplify the process of extracting image-related data from the element model.
## Import
```ts
import { ImageUtility } from "@brizy/core";
```

## Example Usage
```ts
// Inside your component
const imgUtils = new ImageUtility();
const imageData = imgUtils.getImageData({ id: imageKey, v: props });
```

## How It Works
The getImageData method reads the base image key (usually the ID of the imageUpload option) and automatically looks for related metadata fields in the element model by appending suffixes to the key:

For example, if the image key is "sectionBg", the utility will look for and return values from the following keys in the model:

- sectionBgImageSrc
- sectionBgImageWidth
- sectionBgImageHeight
- sectionBgImageFileName
- sectionBgImageExtension

## Returned Data Structure
The result is a typed object of shape:
```ts
export interface ImageData {
  src: string;
  fileName: string;
  extension: string;
  width: number;
  height: number;
}
```
This makes it easy to access all necessary image details for rendering or further processing.