npm package: @luna-park/plugin
Description: Plugin helper for Luna Park.
Author: Luna Park
Latest version: 1.4.2

# @luna-park/plugin

This package provides the core types and helper functions for creating plugins for **Luna Park**, a visual scripting platform.

It exports the necessary interfaces to define plugin configurations, editor components, logic nodes, and lifecycle hooks.

## Installation

```bash
npm install @luna-park/plugin
```

## Usage

The primary way to define a plugin is using the `makePlugin` helper function. This ensures type safety for your plugin configuration.

```typescript
import { makePlugin, ELogicType } from "@luna-park/plugin";
import awesomeIcon from "./awesome-icon.svg"; // Icon URL

export default makePlugin({
    id: "my-awesome-plugin",
    name: "My Awesome Plugin",
    icon: awesomeIcon, // Icon URL
    description: "Adds amazing capabilities to Luna Park.",

    // Plugin configuration schema (optional)
    config: LogicType.object({
        apiKey: LogicType.string(),
        theme: LogicType.string({enum: ["light", "dark"], default: "dark"}),
    }),

    // Lifecycle hooks (optional)
    lifecycle: {
        mount: async (env) => {
            console.log("Plugin mounted", env.config.apiKey);
        },
        update: async ({config}) => {
            console.log("Config updated", config);
        },
        unmount: (env) => {
            console.log("Plugin unmounted");
        },
    },

    // Extend the editor
    editor: {
        // Register custom Vue components for the editor (optional)
        components: [
            {
                name: "Element/Avatar",
                component: MyAvatarComponent,
                properties: {
                    src: LogicType.string({ name: "Avatar URL" }),
                    name: LogicType.string({ name: "Name" }),
                },
                slots: {
                    default: LogicType.void()
                }
            }
            // ... component definitions
        ],
        
        // Register custom logic nodes (optional)
        nodes: [
            makeLogicNode({
                name: "log/stuff",
                inputs: {
                    in_exec: LogicType.exec(),
                    in_stuff: LogicType.string({ name: "Stuff" })
                },
                outputs: {
                    out_exec: LogicType.exec()
                },
                methods: {
                    async in_exec() {
                        console.log(this.in_stuff);
                        await this.out_exec();
                    }
                },
                display: {
                    name: "Log stuff"
                }
            })
            // ... node definitions
        ],
        
        // Register wrapper for the editor (optional)
        wrapper : MyWrapperComponent,
    },
    
    // Code injection options (optional)
    inject: {
        css: "body { background-color: #000; }",
        js: "console.log('Hello world!')"
    }
});
```

## API Reference

### `makePlugin(plugin)`

A helper identity function that takes a `TPlugin` object and returns it. It is used to infer types for the configuration and internal state.

### `TPlugin<TConfig, TInternal>`

The main interface for defining a plugin.

| Property | Type | Description |
| :--- | :--- | :--- |
| `id` | `string` | **Required**. Unique identifier for the plugin. |
| `name` | `string` | **Required**. Display name of the plugin. |
| `icon` | `string` | **Required**. Icon for the plugin. |
| `description` | `string` | Brief description of what the plugin does. |
| `config` | `TSchema` | Schema definition for the plugin's configuration settings. |
| `lifecycle` | `object` | Lifecycle hooks (`mount`, `unmount`, `update`). |
| `editor` | `object` | Extensions for the editor (components, nodes, tokens, wrapper). |
| `build` | `object` | Build-time configurations (Vite plugins, imports). |
| `inject` | `object` | CSS/JS injection options. |

### `TEnv<TConfig, TInternal>`

The environment object passed to lifecycle hooks and dynamic options.

| Property    | Type                  | Description |
|:------------|:----------------------| :--- |
| `app`       | `TApplication`  | Access to the core application instance. |
| `config`    | `Static<TConfig>`     | The resolved configuration values based on the schema. |
| `mode`      | `"build" \| "editor"` | The current running mode. |
| `internals` | `TInternals`          | Internal state (if defined). |

### `TOption<TEnv, T>`

Many properties in `TPlugin` can be either a static value `T` or a function that returns `T` (or `Promise<T>`). This allows for dynamic configuration based on the environment.

```typescript
type TOption<TEnv, T> = T | ((env: TEnv) => T | Promise<T>);
```