@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.