k3-plugin-api 1.3.0 → 1.4.0

package/README.md

@@ -62,6 +62,69 @@ export default plugin;
 
 K3 plugins can extend three layers of the configurator.
 
+### Runtime Hooks
+
+Plugins can access K3 configurator state at runtime using React hooks. These hooks are automatically injected when the plugin is loaded.
+
+```ts
+import { useSettings, useBOM, usePrice } from "k3-plugin-api";
+
+const MyComponent = () => {
+  // Access plugin-specific settings
+  const settings = useSettings("acme.my-plugin");
+  
+  // Access current Bill-of-Materials
+  const bom = useBOM();
+  
+  // Access current total price
+  const price = usePrice();
+  
+  return (
+    <div>
+      <p>API Key: {settings.apiKey}</p>
+      <p>Total items: {bom.length}</p>
+      <p>Price: €{price}</p>
+    </div>
+  );
+};
+```
+
+Available hooks:
+- `useSettings(pluginId: string)` — Access settings for a specific plugin
+- `useBOM()` — Get current Bill-of-Materials entries
+- `usePrice()` — Get current total price (MOV-adjusted or overall)
+
+### `settings` — Plugin Settings Component
+
+Plugins can provide a settings UI component that will be rendered in the K3 admin panel. This allows administrators to configure plugin-specific options that are persisted per plugin instance.
+
+```ts
+import type { K3PluginDescriptor } from "k3-plugin-api";
+
+const SettingsComponent = ({ settings, onSave }) => {
+  return (
+    <div>
+      <input
+        value={settings.apiKey || ""}
+        onChange={(e) => onSave({ ...settings, apiKey: e.target.value })}
+      />
+    </div>
+  );
+};
+
+const plugin: K3PluginDescriptor = {
+  id: "acme.my-plugin",
+  version: "1.0.0",
+  settings: SettingsComponent,
+};
+```
+
+The `settings` component receives:
+- `settings: unknown` — The current settings object (initially `{}`)
+- `onSave: (settings: unknown) => void` — Callback to persist updated settings
+
+Settings are stored per plugin instance and can be accessed at runtime via the plugin's configuration.
+
 ### `ui` — UI Extensions
 
 | Property     | Description                                                                                   |
@@ -124,16 +187,18 @@ const plugin: K3PluginDescriptor = {
 
 ## Key Types
 
-| Type                        | Description                                                    |
-| --------------------------- | -------------------------------------------------------------- |
-| `K3PluginDescriptor`        | Root descriptor object exported by a plugin                    |
-| `HOC<P>`                    | Higher-Order Component: `(Default: FC<P>) => FC<P>`            |
-| `VariableVisualisation`     | Descriptor for a custom input visualisation                    |
-| `K3VariableComponentProps`  | Props injected into a custom variable renderer                 |
-| `DynamicModel`              | 3D model type definition for the viewer                        |
-| `K3Configuration`           | A persisted configuration with code, price, and selection JSON |
-| `K3ConfigurationSavedEvent` | Event payload dispatched on completed save                     |
-| `VariableType`              | Const enum of all variable types                               |
+| Type                        | Description                                                     |
+| --------------------------- | --------------------------------------------------------------- |
+| `K3PluginDescriptor`        | Root descriptor object exported by a plugin                     |
+| `K3Hooks`                   | Runtime hooks interface (useSettings, useBOM, usePrice)         |
+| `HOC<P>`                    | Higher-Order Component: `(Default: FC<P>) => FC<P>`             |
+| `VariableVisualisation`     | Descriptor for a custom input visualisation                     |
+| `K3VariableComponentProps`  | Props injected into a custom variable renderer                  |
+| `DynamicModel`              | 3D model type definition for the viewer                         |
+| `K3Configuration`           | A persisted configuration with code, price, and selection JSON  |
+| `K3ConfigurationSavedEvent` | Event payload dispatched on completed save                      |
+| `K3BomEntry`                | Single Bill-of-Materials entry                                  |
+| `VariableType`              | Const enum of all variable types                                |
 
 ---
 

package/index.ts

@@ -1,5 +1,62 @@
 import type React from "react";
 
+// ─── Plugin Runtime Hooks ───────────────────────────────────────────────────
+
+/**
+ * K3 runtime hooks available to plugins after initialization.
+ * Set via `init()` when the plugin is loaded.
+ */
+export interface K3Hooks {
+  /**
+   * React hook to access plugin-specific settings.
+   * @param pluginId - The unique plugin ID (e.g. "acme.my-plugin")
+   * @returns The settings object for this plugin, or `{}` if none are configured
+   */
+  useSettings: (pluginId: string) => unknown;
+  /**
+   * React hook to access the current Bill-of-Materials.
+   * @returns Array of BOM entries derived from the current selection
+   */
+  useBOM: () => K3BomEntry[];
+  /**
+   * React hook to access the current total price.
+   * @returns The effective total price (MOV-adjusted or overall price)
+   */
+  usePrice: () => number;
+}
+
+/**
+ * Hook functions injected by K3 at runtime.
+ * Use these in your plugin components to access configurator state.
+ */
+export let useSettings: K3Hooks["useSettings"] = () => {
+  throw new Error(
+    "k3-plugin-api not initialized. Make sure K3 calls init() before using hooks.",
+  );
+};
+
+export let useBOM: K3Hooks["useBOM"] = () => {
+  throw new Error(
+    "k3-plugin-api not initialized. Make sure K3 calls init() before using hooks.",
+  );
+};
+
+export let usePrice: K3Hooks["usePrice"] = () => {
+  throw new Error(
+    "k3-plugin-api not initialized. Make sure K3 calls init() before using hooks.",
+  );
+};
+
+/**
+ * Called by K3 when the plugin is loaded to inject runtime hooks.
+ * @internal This function is called by K3 automatically - plugins should not call it directly.
+ */
+export function init(hooks: K3Hooks): void {
+  useSettings = hooks.useSettings;
+  useBOM = hooks.useBOM;
+  usePrice = hooks.usePrice;
+}
+
 // ─── HOC type (mirrors K3 internal, no K3 imports) ──────────────────────────
 
 /** A Higher-Order Component: takes the default component, returns a new one. */
@@ -43,6 +100,10 @@ export interface K3PluginDescriptor {
   viewer?: K3ViewerExtensions;
   /** Logic/callback hooks: config, camera, core. */
   logic?: K3LogicExtensions;
+  settings?: React.ComponentType<{
+    settings: unknown;
+    onSave: (settings: unknown) => void;
+  }>;
 
   /** @deprecated Use viewer.models instead. */
   dynamicModels?: DynamicModel[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "k3-plugin-api",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Official TypeScript types and plugin API for the K3 product configurator",
   "main": "index.js",
   "types": "index.ts",
@@ -25,14 +25,15 @@
   ],
   "author": "ObjectCode GmbH <info@objectcode.de> (https://k3-konfigurator.de/)",
   "license": "MIT",
+  "scripts": {
+    "prepublishOnly": "tsc --emitDeclarationOnly",
+    "yalc": "pnpm prepublishOnly && yalc publish"
+  },
   "peerDependencies": {
     "react": ">=19"
   },
   "devDependencies": {
     "typescript": "^5.8.3",
     "@types/react": "^19.0.0"
-  },
-  "scripts": {
-    "yalc": "pnpm prepublishOnly && yalc publish"
   }
-}
+}