mirror of https://github.com/artf/grapesjs.git
Browse Source
* Setup new local plugin manager * Clean up exports * Cleanup tracking * Cleanups * Cleanup plugins doc * Update findGlobalPluginId * Update plugin docs * Update plugin docs * Add ComponentMatcher to find methods * Update findType * Update old plugin manager tests * Up ignore files * Up TSrelease-v0.23.1-rc.0
Artur Arseniev
4 months ago
committed by
GitHub
GitHub
24 changed files with 912 additions and 256 deletions
@ -1,5 +1,6 @@ |
|||
docs/**/*.md |
|||
dist/ |
|||
private/ |
|||
pnpm-lock.yaml |
|||
packages/cli/src/template/**/*.* |
|||
**/locale/** |
|||
|
|||
@ -1,83 +1,223 @@ |
|||
import { isString } from 'underscore'; |
|||
import Editor from '../editor'; |
|||
import { getGlobal } from '../utils/mixins'; |
|||
import { isFunction, isString } from 'underscore'; |
|||
import { ItemManagerModule, ModuleConfig } from '../abstract/Module'; |
|||
import BlocksEvents from '../block_manager/types'; |
|||
import DeviceEvents from '../device_manager/types'; |
|||
import { ComponentsEvents } from '../dom_components/types'; |
|||
import EditorModel from '../editor/model/Editor'; |
|||
import type { EditorEvent, EditorEventCallbacks } from '../editor/types'; |
|||
import { KeymapsEvents } from '../keymaps/types'; |
|||
import { StyleManagerEvents } from '../style_manager/types'; |
|||
import PluginModel, { createPluginAdded } from './model/Plugin'; |
|||
import Plugins from './model/Plugins'; |
|||
import { Plugin, PluginCleanup, PluginInput, PluginItem, PluginOptions, PluginsEvents, PluginTarget } from './types'; |
|||
import { getPlugin, getPluginId, isPluginDescriptor, isPluginFunction, logPluginWarn, unwrapPluginMeta } from './utils'; |
|||
|
|||
type PluginOptions = Record<string, any>; |
|||
export default class PluginManager extends ItemManagerModule<ModuleConfig, Plugins> { |
|||
events = PluginsEvents; |
|||
storageKey = ''; |
|||
|
|||
export type Plugin<T extends PluginOptions = {}> = (editor: Editor, config: T) => void; |
|||
constructor(em: EditorModel) { |
|||
super(em, 'PluginManager', new Plugins(), PluginsEvents, {}); |
|||
} |
|||
|
|||
get editor() { |
|||
return this.em.getEditor(); |
|||
} |
|||
|
|||
private getConfigPluginOptions(id: string, sourcePlugin: string | Plugin<any>) { |
|||
const pluginsOpts = this.editor.getConfig().pluginsOpts || {}; |
|||
const inlineKey = isFunction(sourcePlugin) ? sourcePlugin.toString() : ''; |
|||
return pluginsOpts[id] || (inlineKey ? pluginsOpts[inlineKey] || {} : {}); |
|||
} |
|||
|
|||
const getPluginById = (pluginId: string, plugins: PluginManager) => { |
|||
let result = plugins.get(pluginId); |
|||
private generatePluginId() { |
|||
return `gjs-plugin:${this._createId(16, 0)}`; |
|||
} |
|||
|
|||
// Try to search in global context
|
|||
if (!result) { |
|||
const wplg = (getGlobal() as any)[pluginId]; |
|||
result = wplg?.default || wplg; |
|||
private resolvePluginId(input: string | Plugin<any>, plugin: Plugin<any>, explicitId?: string) { |
|||
return explicitId || (isString(input) ? input : '') || getPluginId(plugin) || this.generatePluginId(); |
|||
} |
|||
|
|||
return result; |
|||
}; |
|||
|
|||
export const getPlugin = (plugin: string | Plugin<any>, plugins: PluginManager) => { |
|||
return isString(plugin) |
|||
? getPluginById(plugin, plugins) |
|||
: (plugin as unknown as { default: Plugin<any> })?.default || plugin; |
|||
}; |
|||
|
|||
export const logPluginWarn = (editor: Editor, plugin: string) => { |
|||
editor.getModel().logWarning(`Plugin ${plugin} not found`, { |
|||
context: 'plugins', |
|||
plugin, |
|||
}); |
|||
}; |
|||
|
|||
export default class PluginManager { |
|||
plugins: Record<string, Plugin> = {}; |
|||
|
|||
/** |
|||
* Add new plugin. Plugins could not be overwritten |
|||
* @param {string} id Plugin ID |
|||
* @param {Function} plugin Function which contains all plugin logic |
|||
* @return {Function} The plugin function |
|||
* @deprecated Don't use named plugins, create plugins as simple functions. More about [Plugins](https://grapesjs.com/docs/modules/Plugins.html)
|
|||
* @example |
|||
* PluginManager.add('some-plugin', function(editor) { |
|||
* editor.Commands.add('new-command', { |
|||
* run: function(editor, senderBtn){ |
|||
* console.log('Executed new-command'); |
|||
* } |
|||
* }) |
|||
* }); |
|||
*/ |
|||
add<T extends PluginOptions>(id: string, plugin: Plugin<T>) { |
|||
const plg = this.get(id); |
|||
|
|||
if (plg) { |
|||
return plg; |
|||
private resolvePluginTarget(target: PluginTarget) { |
|||
if (target instanceof PluginModel) return target; |
|||
|
|||
if (isString(target)) return this.get(target); |
|||
|
|||
const { plugin } = unwrapPluginMeta(target as Plugin<any>); |
|||
if (!isPluginFunction(plugin)) return; |
|||
|
|||
return this.getAll().find((item) => item.get('plugin') === plugin); |
|||
} |
|||
|
|||
private normalizePlugin(input: PluginInput, options: PluginOptions = {}) { |
|||
const descriptor = isPluginDescriptor(input) ? input : undefined; |
|||
const sourcePlugin = (descriptor ? descriptor.plugin : input) as string | Plugin<any>; |
|||
const explicitId = descriptor?.id || ''; |
|||
const unwrapped = unwrapPluginMeta(sourcePlugin); |
|||
const resolvedPlugin = getPlugin(unwrapped.plugin); |
|||
let normalized; |
|||
|
|||
if (!resolvedPlugin || !isPluginFunction(resolvedPlugin)) { |
|||
const pluginId = isString(unwrapped.plugin) ? unwrapped.plugin : getPluginId(unwrapped.plugin) || explicitId; |
|||
if (explicitId) { |
|||
throw new Error(`Plugin ${explicitId} not found`); |
|||
} |
|||
logPluginWarn(this.editor, pluginId || 'unknown'); |
|||
} else { |
|||
const id = explicitId || this.resolvePluginId(sourcePlugin, resolvedPlugin); |
|||
normalized = { |
|||
id, |
|||
plugin: resolvedPlugin, |
|||
options: { |
|||
...this.getConfigPluginOptions(id, sourcePlugin), |
|||
...unwrapped.options, |
|||
...options, |
|||
}, |
|||
}; |
|||
} |
|||
|
|||
// @ts-ignore
|
|||
this.plugins[id] = plugin; |
|||
return normalized; |
|||
} |
|||
|
|||
private createAddedTracker() { |
|||
const added = createPluginAdded(); |
|||
const cleanup: PluginCleanup[] = []; |
|||
const { editor } = this; |
|||
const listeners: Array<[EditorEvent, (...args: any[]) => void]> = []; |
|||
const listen = <E extends EditorEvent & keyof EditorEventCallbacks>( |
|||
event: E, |
|||
callback: (...args: EditorEventCallbacks[E]) => void, |
|||
) => { |
|||
editor.on(event, callback as any); |
|||
listeners.push([event, callback]); |
|||
}; |
|||
|
|||
listen(BlocksEvents.add, (block) => { |
|||
const id = block.get('id'); |
|||
if (!id || added.blocks.includes(id)) return; |
|||
added.blocks.push(id); |
|||
cleanup.push(() => editor.Blocks.remove(id)); |
|||
}); |
|||
|
|||
listen(KeymapsEvents.add, (keymap) => { |
|||
const id = keymap.id; |
|||
if (!id || added.keymaps.includes(id)) return; |
|||
added.keymaps.push(id); |
|||
cleanup.push(() => editor.Keymaps.remove(id)); |
|||
}); |
|||
|
|||
listen(ComponentsEvents.typeAdd, (type) => { |
|||
const id = type.id; |
|||
if (!id || added.componentTypes.includes(id)) return; |
|||
added.componentTypes.push(id); |
|||
cleanup.push(() => editor.Components.removeType(id)); |
|||
}); |
|||
|
|||
listen(DeviceEvents.add, (device) => { |
|||
const id = device.get('id'); |
|||
if (!id || added.devices.includes(id)) return; |
|||
added.devices.push(id); |
|||
cleanup.push(() => editor.Devices.remove(id)); |
|||
}); |
|||
|
|||
listen(StyleManagerEvents.sectorAdd, (sector) => { |
|||
const id = sector.get('id'); |
|||
if (!id || added.styleSectors.includes(id)) return; |
|||
added.styleSectors.push(id); |
|||
cleanup.push(() => editor.StyleManager.removeSector(id)); |
|||
}); |
|||
|
|||
return { |
|||
added, |
|||
stop: () => listeners.forEach(([event, callback]) => editor.off(event, callback)), |
|||
cleanup: () => { |
|||
cleanup |
|||
.slice() |
|||
.reverse() |
|||
.forEach((cb) => cb()); |
|||
}, |
|||
}; |
|||
} |
|||
|
|||
add(input: PluginInput, options: PluginOptions = {}): PluginItem | undefined { |
|||
const normalized = this.normalizePlugin(input, options); |
|||
if (!normalized) return; |
|||
|
|||
const existing = this.get(normalized.id); |
|||
if (existing) return existing; |
|||
|
|||
const tracking = this.createAddedTracker(); |
|||
let result: unknown; |
|||
|
|||
try { |
|||
result = normalized.plugin(this.editor, normalized.options); |
|||
} catch (error) { |
|||
tracking.stop(); |
|||
tracking.cleanup(); |
|||
throw error; |
|||
} |
|||
|
|||
tracking.stop(); |
|||
|
|||
const plugin = new PluginModel({ |
|||
id: normalized.id, |
|||
plugin: normalized.plugin, |
|||
options: normalized.options, |
|||
added: tracking.added, |
|||
cleanup: () => {}, |
|||
}); |
|||
|
|||
let cleaned = false; |
|||
const builtInCleanup = () => { |
|||
if (cleaned) return; |
|||
cleaned = true; |
|||
tracking.cleanup(); |
|||
}; |
|||
|
|||
const cleanup = () => { |
|||
if (cleaned) return; |
|||
const customCleanup = isFunction(result) ? result : null; |
|||
|
|||
if (customCleanup) { |
|||
customCleanup({ |
|||
cleanup: builtInCleanup, |
|||
editor: this.editor, |
|||
plugin, |
|||
}); |
|||
} else { |
|||
builtInCleanup(); |
|||
} |
|||
}; |
|||
|
|||
plugin.set('cleanup', cleanup); |
|||
this.all.add(plugin); |
|||
return plugin; |
|||
} |
|||
|
|||
/** |
|||
* Returns plugin by ID |
|||
* @param {string} id Plugin ID |
|||
* @return {Function|undefined} Plugin |
|||
* @example |
|||
* var plugin = PluginManager.get('some-plugin'); |
|||
* plugin(editor); |
|||
*/ |
|||
get<T extends PluginOptions>(id: string): Plugin<T> | undefined { |
|||
return this.plugins[id]; |
|||
get(id: string): PluginItem | undefined { |
|||
return this.all.get(id); |
|||
} |
|||
|
|||
getAll(): PluginItem[] { |
|||
return [...this.all.models]; |
|||
} |
|||
|
|||
remove(target: PluginTarget, opts: Record<string, any> = {}): PluginItem | undefined { |
|||
const plugin = this.resolvePluginTarget(target); |
|||
if (!plugin) return; |
|||
|
|||
const { em, events } = this; |
|||
const rm = () => { |
|||
plugin.get('cleanup')?.(); |
|||
this.all.remove(plugin, opts); |
|||
return plugin; |
|||
}; |
|||
|
|||
!opts.silent && em.trigger(events.removeBefore, plugin, rm, opts); |
|||
return !opts.abort ? rm() : undefined; |
|||
} |
|||
|
|||
/** |
|||
* Returns object with all plugins |
|||
*/ |
|||
getAll() { |
|||
return this.plugins; |
|||
destroy() { |
|||
this.__destroy(); |
|||
} |
|||
} |
|||
|
|||
@ -0,0 +1,26 @@ |
|||
import { Model } from '../../common'; |
|||
import type { PluginItemProps, PluginAdded } from '../types'; |
|||
|
|||
export const createPluginAdded = (): PluginAdded => ({ |
|||
blocks: [], |
|||
commands: [], |
|||
keymaps: [], |
|||
componentTypes: [], |
|||
devices: [], |
|||
traitTypes: [], |
|||
styleTypes: [], |
|||
assetTypes: [], |
|||
styleSectors: [], |
|||
}); |
|||
|
|||
export default class PluginModel extends Model<PluginItemProps> { |
|||
defaults(): PluginItemProps { |
|||
return { |
|||
id: '', |
|||
plugin: (() => {}) as PluginItemProps['plugin'], |
|||
options: {}, |
|||
added: createPluginAdded(), |
|||
cleanup: () => {}, |
|||
}; |
|||
} |
|||
} |
|||
@ -0,0 +1,6 @@ |
|||
import { Collection } from '../../common'; |
|||
import PluginModel from './Plugin'; |
|||
|
|||
export default class Plugins extends Collection<PluginModel> {} |
|||
|
|||
Plugins.prototype.model = PluginModel; |
|||
@ -0,0 +1,112 @@ |
|||
import { |
|||
EventCallbackAdd, |
|||
EventCallbackAll, |
|||
EventCallbackRemove, |
|||
EventCallbackRemoveBefore, |
|||
EventCallbackUpdate, |
|||
Model, |
|||
} from '../common'; |
|||
import type Editor from '../editor'; |
|||
|
|||
export type PluginOptions = Record<string, any>; |
|||
|
|||
export interface PluginAdded { |
|||
blocks: string[]; |
|||
commands: string[]; |
|||
keymaps: string[]; |
|||
componentTypes: string[]; |
|||
devices: string[]; |
|||
traitTypes: string[]; |
|||
styleTypes: string[]; |
|||
assetTypes: string[]; |
|||
styleSectors: string[]; |
|||
} |
|||
|
|||
export type PluginCleanup = () => void; |
|||
|
|||
export type PluginResult = void | PluginCleanupHandler | object | null | undefined; |
|||
|
|||
export interface Plugin<T extends PluginOptions = {}> { |
|||
(editor: Editor, config: T): PluginResult; |
|||
__gjsPluginId?: string; |
|||
} |
|||
|
|||
export interface PluginDescriptor { |
|||
id: string; |
|||
plugin: Plugin<any>; |
|||
} |
|||
|
|||
export interface PluginWithMeta<T extends PluginOptions = {}> extends Plugin<T> { |
|||
__gjsPluginMeta?: { |
|||
plugin: string | Plugin<any>; |
|||
options?: T; |
|||
id?: string; |
|||
}; |
|||
} |
|||
|
|||
export type PluginInput = string | Plugin<any> | PluginDescriptor; |
|||
|
|||
export interface PluginItemProps { |
|||
id: string; |
|||
plugin: Plugin<any>; |
|||
options: Record<string, any>; |
|||
added: PluginAdded; |
|||
cleanup: PluginCleanup; |
|||
} |
|||
|
|||
export type PluginItem = Model<PluginItemProps>; |
|||
|
|||
export type PluginTarget = string | Plugin<any> | PluginItem; |
|||
|
|||
export type PluginCleanupHandler = (ctx: { cleanup: PluginCleanup; plugin: PluginItem }) => void; |
|||
|
|||
export type PluginEvent = `${PluginsEvents}`; |
|||
|
|||
/**{START_EVENTS}*/ |
|||
export enum PluginsEvents { |
|||
/** |
|||
* @event `plugin:add` Plugin installed in the editor. |
|||
* @example |
|||
* editor.on('plugin:add', (plugin) => { ... }); |
|||
*/ |
|||
add = 'plugin:add', |
|||
|
|||
/** |
|||
* @event `plugin:remove` Plugin removed from the editor. |
|||
* @example |
|||
* editor.on('plugin:remove', (plugin) => { ... }); |
|||
*/ |
|||
remove = 'plugin:remove', |
|||
|
|||
/** |
|||
* @event `plugin:remove:before` Triggered before plugin removal. |
|||
* @example |
|||
* editor.on('plugin:remove:before', (plugin, remove, opts) => { ... }); |
|||
*/ |
|||
removeBefore = 'plugin:remove:before', |
|||
|
|||
/** |
|||
* @event `plugin:update` Plugin updated. |
|||
* @example |
|||
* editor.on('plugin:update', (plugin, changes) => { ... }); |
|||
*/ |
|||
update = 'plugin:update', |
|||
|
|||
/** |
|||
* @event `plugin` Catch-all event for plugin changes. |
|||
* @example |
|||
* editor.on('plugin', ({ event, model, ... }) => { ... }); |
|||
*/ |
|||
all = 'plugin', |
|||
} |
|||
/**{END_EVENTS}*/ |
|||
|
|||
export interface PluginsEventCallback { |
|||
[PluginsEvents.add]: EventCallbackAdd<PluginItem>; |
|||
[PluginsEvents.remove]: EventCallbackRemove<PluginItem>; |
|||
[PluginsEvents.removeBefore]: EventCallbackRemoveBefore<PluginItem>; |
|||
[PluginsEvents.update]: EventCallbackUpdate<PluginItem>; |
|||
[PluginsEvents.all]: EventCallbackAll<PluginEvent, PluginItem>; |
|||
} |
|||
|
|||
export default PluginsEvents; |
|||
@ -0,0 +1,114 @@ |
|||
import { isFunction, isString } from 'underscore'; |
|||
import type Editor from '../editor'; |
|||
import { getGlobal } from '../utils/mixins'; |
|||
import type { Plugin, PluginDescriptor, PluginOptions, PluginWithMeta } from './types'; |
|||
|
|||
const LEGACY_PLUGIN_ERROR = |
|||
'grapesjs.plugins.add(...) is deprecated. Pass plugins directly via init({ plugins: [...] }) or use usePlugin(...).'; |
|||
|
|||
const legacyPlugins = new Map<string, Plugin<any>>(); |
|||
|
|||
export const isPluginFunction = (value: unknown): value is Plugin<any> => isFunction(value); |
|||
|
|||
export const isPluginDescriptor = (value: unknown): value is PluginDescriptor => |
|||
!!value && typeof value === 'object' && !isFunction(value) && 'plugin' in value; |
|||
|
|||
export const unwrapPluginMeta = ( |
|||
plugin: string | Plugin<any>, |
|||
): { plugin: string | Plugin<any>; options: PluginOptions; id?: string } => { |
|||
let current = plugin; |
|||
const options: PluginOptions = {}; |
|||
let id: string | undefined; |
|||
|
|||
while (isPluginFunction(current) && (current as PluginWithMeta<any>).__gjsPluginMeta) { |
|||
const meta = (current as PluginWithMeta<any>).__gjsPluginMeta!; |
|||
current = meta.plugin; |
|||
Object.assign(options, meta.options || {}); |
|||
id = id || meta.id; |
|||
} |
|||
|
|||
return { plugin: current, options, id }; |
|||
}; |
|||
|
|||
export const getLegacyPlugin = (pluginId: string) => legacyPlugins.get(pluginId); |
|||
|
|||
export const getLegacyPlugins = () => legacyPlugins; |
|||
|
|||
export const clearLegacyPlugins = () => legacyPlugins.clear(); |
|||
|
|||
export const addLegacyPlugin = <T extends PluginOptions>(id: string, plugin: Plugin<T>) => { |
|||
console.error(LEGACY_PLUGIN_ERROR); |
|||
legacyPlugins.set(id, plugin); |
|||
return plugin; |
|||
}; |
|||
|
|||
export const legacyGlobalPlugins = { |
|||
add: addLegacyPlugin, |
|||
get: getLegacyPlugin, |
|||
getAll: getLegacyPlugins, |
|||
clear: clearLegacyPlugins, |
|||
}; |
|||
|
|||
export const findLegacyPluginId = (plugin: Plugin<any>) => { |
|||
let result = ''; |
|||
legacyPlugins.forEach((storedPlugin, id) => { |
|||
if (!result && storedPlugin === plugin) { |
|||
result = id; |
|||
} |
|||
}); |
|||
return result || undefined; |
|||
}; |
|||
|
|||
export const findGlobalPluginId = (plugin: Plugin<any>) => { |
|||
const globalPlugins = getGlobal() as Record<string, any>; |
|||
|
|||
return Object.keys(globalPlugins).find((id) => { |
|||
try { |
|||
const globalPlugin = globalPlugins[id]; |
|||
return globalPlugin === plugin || globalPlugin?.default === plugin; |
|||
} catch (error) { |
|||
return false; |
|||
} |
|||
}); |
|||
}; |
|||
|
|||
export const getPluginId = (plugin: Plugin<any>) => |
|||
plugin.__gjsPluginId || findLegacyPluginId(plugin) || findGlobalPluginId(plugin); |
|||
|
|||
export const getPluginById = (pluginId: string) => { |
|||
const legacy = getLegacyPlugin(pluginId); |
|||
|
|||
if (legacy) return legacy; |
|||
|
|||
const globalPlugin = (getGlobal() as any)[pluginId]; |
|||
return globalPlugin?.default || globalPlugin; |
|||
}; |
|||
|
|||
export const getPlugin = (plugin: string | Plugin<any>): Plugin<any> | undefined => { |
|||
const { plugin: unwrapped } = unwrapPluginMeta(plugin); |
|||
return isString(unwrapped) |
|||
? getPluginById(unwrapped) |
|||
: (unwrapped as unknown as { default?: Plugin<any> })?.default || unwrapped; |
|||
}; |
|||
|
|||
export const logPluginWarn = (editor: Editor, plugin: string) => { |
|||
editor.getModel().logWarning(`Plugin ${plugin} not found`, { context: 'plugins', plugin }); |
|||
}; |
|||
|
|||
export const usePlugin = <P extends Plugin<any> | string>(plugin: P, opts?: P extends Plugin<infer C> ? C : {}) => { |
|||
const options = opts || {}; |
|||
const wrapped: PluginWithMeta<any> = (editor: Editor) => { |
|||
const pluginResult = getPlugin(plugin); |
|||
|
|||
if (pluginResult) { |
|||
pluginResult(editor, options); |
|||
} else { |
|||
logPluginWarn(editor, plugin as string); |
|||
} |
|||
}; |
|||
|
|||
const id = typeof plugin === 'string' ? plugin : plugin.__gjsPluginId; |
|||
wrapped.__gjsPluginMeta = { id, plugin, options }; |
|||
|
|||
return wrapped; |
|||
}; |
|||
Loading…
Reference in new issue