@tabularis/plugin-api

@tabularis/plugin-api

Public API surface for Tabularis plugin UI extensions.

Plugin bundles import hooks, the defineSlot helper, and shared types from this package. The Tabularis host injects the actual runtime implementation — the published package ships as thin stubs, so your bundle stays small and the host remains the single source of truth.

Install

npm install --save-dev @tabularis/plugin-api
# or: pnpm add -D @tabularis/plugin-api

Treat @tabularis/plugin-api and react as Vite externals when building your IIFE bundle — the host provides both at runtime.

Quick start — a typed slot component

import { defineSlot, usePluginConnection } from "@tabularis/plugin-api";

const MySlot = defineSlot(
  "row-editor-sidebar.field.after",
  ({ context }) => {
    const { driver } = usePluginConnection();
    // context.columnName is `string` (not `string | undefined`) because the
    // chosen slot always provides it.
    return <div>{driver} · {context.columnName}</div>;
  },
);

export default MySlot.component;

Hooks

Hook	Returns	Purpose
usePluginQuery()	{ executeQuery, loading, error }	Execute read-only queries on the active connection
usePluginConnection()	{ connectionId, driver, schema }	Active connection metadata
usePluginToast()	{ showInfo, showError, showWarning }	System notifications
usePluginModal()	{ openModal, closeModal }	Host-managed modal with custom content
usePluginSetting(pluginId)	{ getSetting, setSetting, setSettings }	Read/write the plugin's own settings
usePluginTheme()	{ themeId, themeName, isDark, colors }	Current theme tokens
usePluginTranslation(pluginId)	t(key)	Plugin-scoped i18next translator
openUrl(url)	Promise<void>	Open a URL in the system browser

All hooks must run inside a React component loaded by Tabularis. Calling them outside the host throws a clear error instead of failing silently.

Compatibility

The package exports API_VERSION and MIN_HOST_VERSION. Plugin authors can opt in to a fail-fast compatibility check at component entry:

import { assertHostCompat } from "@tabularis/plugin-api";
assertHostCompat(); // throws if the running Tabularis is older than MIN_HOST_VERSION

Package version	Minimum Tabularis	Notes
0.1.0	0.1.0 (see host HOST_API_VERSION)	Initial release

Slot reference

See the full slot list and context contracts in plugins/PLUGIN_GUIDE.md § 3b and the typed SlotContextMap in src/slots.ts.

License

Apache-2.0, same as Tabularis.