@bquery/bquery 1.5.0 → 1.7.0

package/src/plugin/registry.ts

@@ -0,0 +1,269 @@
+/**
+ * Global plugin registry for bQuery.
+ *
+ * Provides `use()` to register plugins and query helpers consumed by
+ * other modules (e.g. the view module reads custom directives from here).
+ *
+ * @module bquery/plugin
+ */
+
+import { registerCustomDirectiveResolver } from '../view/custom-directives';
+import type {
+  BQueryPlugin,
+  CustomDirective,
+  CustomDirectiveHandler,
+  PluginInstallContext,
+} from './types';
+
+// ---------------------------------------------------------------------------
+// Internal registries
+// ---------------------------------------------------------------------------
+
+/** Set of installed plugin names — prevents double-install. */
+const installedPlugins = new Set<string>();
+
+/** Custom directives contributed by plugins. */
+const customDirectives = new Map<string, CustomDirectiveHandler>();
+
+type PendingComponentRegistration = {
+  tagName: string;
+  constructor: CustomElementConstructor;
+  options?: ElementDefinitionOptions;
+};
+
+registerCustomDirectiveResolver((name) => customDirectives.get(name));
+
+/**
+ * Restore the directive registry to a previously captured snapshot.
+ *
+ * Used to roll back partial plugin installation when `install()` or staged
+ * `customElements.define()` calls fail after directives were already registered.
+ *
+ * @internal
+ */
+const restoreDirectiveSnapshot = (
+  directivesSnapshot: ReadonlyMap<string, CustomDirectiveHandler>
+): void => {
+  customDirectives.clear();
+  for (const [name, handler] of directivesSnapshot) {
+    customDirectives.set(name, handler);
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Install context factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the `PluginInstallContext` handed to each plugin's `install()`.
+ * @internal
+ */
+const createInstallContext = (
+  pendingComponents: PendingComponentRegistration[]
+): PluginInstallContext => ({
+  directive(name: string, handler: CustomDirectiveHandler): void {
+    if (typeof name !== 'string' || name.length === 0) {
+      throw new Error('bQuery plugin directive: name must be a non-empty string');
+    }
+    if (name.startsWith('bq-')) {
+      const suggestedName = name.slice(3);
+      throw new Error(
+        `bQuery plugin directive: name "${name}" must be provided without the "bq-" prefix` +
+          (suggestedName ? ` (use "${suggestedName}")` : '')
+      );
+    }
+    if (typeof handler !== 'function') {
+      throw new Error(`bQuery plugin directive: handler for "${name}" must be a function`);
+    }
+    if (customDirectives.has(name)) {
+      throw new Error(`bQuery plugin directive: a directive named "${name}" is already registered`);
+    }
+    customDirectives.set(name, handler);
+  },
+
+  component(
+    tagName: string,
+    constructor: CustomElementConstructor,
+    options?: ElementDefinitionOptions
+  ): void {
+    if (typeof tagName !== 'string' || tagName.length === 0) {
+      throw new Error('bQuery plugin component: tagName must be a non-empty string');
+    }
+    if (!tagName.includes('-')) {
+      throw new Error(
+        `bQuery plugin component: tagName "${tagName}" must be a valid custom element name containing a hyphen`
+      );
+    }
+    if (typeof constructor !== 'function') {
+      throw new Error(`bQuery plugin component: constructor for "${tagName}" must be a function`);
+    }
+    if (typeof customElements === 'undefined') {
+      if (typeof console !== 'undefined' && typeof console.warn === 'function') {
+        console.warn(
+          `[bQuery] plugin component "${tagName}" was not registered because customElements is not available in this environment.`
+        );
+      }
+      return;
+    }
+    // Idempotent — skip if already defined or already staged during this install
+    if (
+      !customElements.get(tagName) &&
+      !pendingComponents.some((entry) => entry.tagName === tagName)
+    ) {
+      pendingComponents.push({ tagName, constructor, options });
+    }
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Register a bQuery plugin.
+ *
+ * Plugins are installed at most once (identified by `plugin.name`).
+ * Duplicate calls with the same name are silently ignored.
+ *
+ * @param plugin - The plugin object implementing `{ name, install }`.
+ * @param options - Optional configuration forwarded to `plugin.install()`.
+ * @throws If `plugin` is not a valid plugin object.
+ *
+ * @example
+ * ```ts
+ * import { use } from '@bquery/bquery/plugin';
+ *
+ * use({
+ *   name: 'highlight',
+ *   install(ctx) {
+ *     ctx.directive('highlight', (el, expr) => {
+ *       (el as HTMLElement).style.background = String(expr);
+ *     });
+ *   },
+ * });
+ * ```
+ */
+export const use = <TOptions = unknown>(
+  plugin: BQueryPlugin<TOptions>,
+  options?: TOptions
+): void => {
+  if (!plugin || typeof plugin !== 'object') {
+    throw new Error('bQuery plugin: use() expects a plugin object with { name, install }');
+  }
+  if (typeof plugin.name !== 'string' || plugin.name.length === 0) {
+    throw new Error('bQuery plugin: plugin must have a non-empty "name" property');
+  }
+  if (typeof plugin.install !== 'function') {
+    throw new Error(`bQuery plugin: plugin "${plugin.name}" must have an "install" function`);
+  }
+
+  // Deduplicate
+  if (installedPlugins.has(plugin.name)) return;
+
+  const pendingComponents: PendingComponentRegistration[] = [];
+  const ctx = createInstallContext(pendingComponents);
+  const directivesSnapshot = new Map(customDirectives);
+
+  try {
+    plugin.install(ctx, options);
+  } catch (error) {
+    restoreDirectiveSnapshot(directivesSnapshot);
+    throw error;
+  }
+
+  try {
+    for (const entry of pendingComponents) {
+      if (!customElements.get(entry.tagName)) {
+        customElements.define(entry.tagName, entry.constructor, entry.options);
+      }
+    }
+  } catch (error) {
+    restoreDirectiveSnapshot(directivesSnapshot);
+    throw error;
+  }
+
+  installedPlugins.add(plugin.name);
+};
+
+/**
+ * Check whether a plugin with the given name has been installed.
+ *
+ * @param name - The plugin name to check.
+ * @returns `true` if the plugin was previously installed via `use()`.
+ *
+ * @example
+ * ```ts
+ * import { isInstalled } from '@bquery/bquery/plugin';
+ *
+ * if (!isInstalled('my-plugin')) {
+ *   use(myPlugin);
+ * }
+ * ```
+ */
+export const isInstalled = (name: string): boolean => installedPlugins.has(name);
+
+/**
+ * Return a read-only snapshot of all installed plugin names.
+ *
+ * @returns Array of plugin name strings.
+ *
+ * @example
+ * ```ts
+ * import { getInstalledPlugins } from '@bquery/bquery/plugin';
+ * console.log(getInstalledPlugins()); // ['my-plugin', 'other-plugin']
+ * ```
+ */
+export const getInstalledPlugins = (): readonly string[] => [...installedPlugins];
+
+/**
+ * Retrieve the handler for a custom directive registered by a plugin.
+ *
+ * This is used internally by the view module's `processElement` to
+ * resolve directives that aren't built-in.
+ *
+ * @param name - Directive name **without** prefix (e.g. `'tooltip'`).
+ * @returns The handler, or `undefined` if none is registered.
+ *
+ * @example
+ * ```ts
+ * import { getCustomDirective } from '@bquery/bquery/plugin';
+ * const handler = getCustomDirective('tooltip');
+ * ```
+ */
+export const getCustomDirective = (name: string): CustomDirectiveHandler | undefined =>
+  customDirectives.get(name);
+
+/**
+ * Return a read-only snapshot of all registered custom directives.
+ *
+ * @returns Array of `{ name, handler }` descriptors.
+ *
+ * @example
+ * ```ts
+ * import { getCustomDirectives } from '@bquery/bquery/plugin';
+ * for (const { name, handler } of getCustomDirectives()) {
+ *   console.log(`Directive: bq-${name}`);
+ * }
+ * ```
+ */
+export const getCustomDirectives = (): readonly CustomDirective[] =>
+  [...customDirectives.entries()].map(([name, handler]) => ({ name, handler }));
+
+/**
+ * Reset all plugin registrations.
+ *
+ * Clears all installed plugins and custom directives.
+ *
+ * This utility is primarily intended for tests and other isolated environments
+ * that need to reinitialize plugin state between runs.
+ *
+ * @example
+ * ```ts
+ * import { resetPlugins } from '@bquery/bquery/plugin';
+ * afterEach(() => resetPlugins());
+ * ```
+ */
+export const resetPlugins = (): void => {
+  installedPlugins.clear();
+  customDirectives.clear();
+};

package/src/plugin/types.ts

@@ -0,0 +1,137 @@
+/**
+ * Public types for the bQuery plugin system.
+ *
+ * Plugins extend bQuery by registering custom directives and Web Components
+ * through a single unified interface.
+ *
+ * @module bquery/plugin
+ */
+
+import type { CleanupFn } from '../reactive/index';
+import type { BindingContext } from '../view/types';
+
+// ---------------------------------------------------------------------------
+// Custom Directive
+// ---------------------------------------------------------------------------
+
+/**
+ * A custom directive handler that is invoked when the view module encounters
+ * a `bq-{name}` attribute during mount processing.
+ *
+ * @param el - The DOM element carrying the directive attribute
+ * @param expression - The raw attribute value (expression string)
+ * @param context - The current binding context (data / signals)
+ * @param cleanups - Array where the handler should push any cleanup functions
+ *
+ * @example
+ * ```ts
+ * const tooltipDirective: CustomDirectiveHandler = (el, expression, ctx, cleanups) => {
+ *   const tip = document.createElement('span');
+ *   tip.textContent = String(expression);
+ *   el.appendChild(tip);
+ *   cleanups.push(() => tip.remove());
+ * };
+ * ```
+ */
+export type CustomDirectiveHandler = (
+  el: Element,
+  expression: string,
+  context: BindingContext,
+  cleanups: CleanupFn[]
+) => void;
+
+/**
+ * Descriptor for a custom directive registered by a plugin.
+ */
+export interface CustomDirective {
+  /** The directive name (without prefix). e.g. `'tooltip'` → `bq-tooltip` */
+  readonly name: string;
+  /** The handler function called when the directive is encountered. */
+  readonly handler: CustomDirectiveHandler;
+}
+
+// ---------------------------------------------------------------------------
+// Plugin Install Context
+// ---------------------------------------------------------------------------
+
+/**
+ * Context object provided to a plugin's `install` function.
+ *
+ * Plugins use these helpers to register their contributions into bQuery's
+ * global registries without directly importing internal modules.
+ */
+export interface PluginInstallContext {
+  /**
+   * Register a custom view directive that will be recognized during
+   * `mount()` processing.
+   *
+   * @param name - Directive name **without** the `bq-` prefix (e.g. `'tooltip'`)
+   * @param handler - The handler called for each element with the directive
+   *
+   * @example
+   * ```ts
+   * ctx.directive('focus', (el) => {
+   *   (el as HTMLElement).focus();
+   * });
+   * ```
+   */
+  directive(name: string, handler: CustomDirectiveHandler): void;
+
+  /**
+   * Register a Web Component via the native `customElements.define()` API.
+   *
+   * @param tagName - Custom element tag (e.g. `'my-counter'`)
+   * @param constructor - The `HTMLElement` subclass
+   * @param options - Optional `ElementDefinitionOptions` (e.g. `{ extends: 'div' }`)
+   *
+   * @example
+   * ```ts
+   * ctx.component('my-counter', MyCounterElement);
+   * ```
+   */
+  component(
+    tagName: string,
+    constructor: CustomElementConstructor,
+    options?: ElementDefinitionOptions
+  ): void;
+}
+
+// ---------------------------------------------------------------------------
+// Plugin Interface
+// ---------------------------------------------------------------------------
+
+/**
+ * A bQuery plugin.
+ *
+ * Plugins are plain objects with a `name` and an `install` function.
+ * Call `use(plugin)` to activate a plugin before creating routers, stores,
+ * or mounting views.
+ *
+ * @example
+ * ```ts
+ * import { use } from '@bquery/bquery/plugin';
+ *
+ * const myPlugin: BQueryPlugin = {
+ *   name: 'my-plugin',
+ *   install(ctx, options) {
+ *     ctx.directive('highlight', (el, expr) => {
+ *       (el as HTMLElement).style.background = String(expr);
+ *     });
+ *   },
+ * };
+ *
+ * use(myPlugin, { color: 'yellow' });
+ * ```
+ */
+export interface BQueryPlugin<TOptions = unknown> {
+  /** Unique human-readable name for the plugin. */
+  readonly name: string;
+
+  /**
+   * Called once when the plugin is registered via `use()`.
+   *
+   * @param context - Helpers for registering directives, components, etc.
+   * @param options - User-provided options forwarded from `use(plugin, options)`.
+   */
+  install(context: PluginInstallContext, options?: TOptions): void;
+}