k3-plugin-api 1.2.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[];
@@ -627,6 +688,65 @@ export interface K3LogicExtensions {
   };
 }
 
+// ─── Model Slot Types ────────────────────────────────────────────────────────
+
+/**
+ * Declares a named slot where child models can be placed inside a parent dynamic model.
+ * Attach an array of these to `DynamicModel.slotDefinitions`.
+ */
+export interface SlotDefinition {
+  /** Unique identifier (UUID) — primary key used in rule columns to reference this slot. */
+  id: string;
+  /** Human-readable name shown in the admin slot picker. */
+  name: string;
+  /** Optional fallback model ID rendered when no rule assigns a model to this slot. */
+  defaultModelId?: string | number;
+}
+
+/**
+ * A resolved model instance placed into a slot at runtime.
+ * Received via `DynamicModelComponentProps.slots[slotId]`.
+ */
+export interface SlotModelInstance {
+  /** The model data object for this slot instance. */
+  model: { id: string | number; [key: string]: unknown };
+  /** URL of the model's 3D file, or `undefined` if this is a dynamic model with a component. */
+  fileURL: string | undefined;
+  /** The React component used to render this model if it is a dynamic model otherwise `undefined`. */
+  component: React.ComponentType<any> | undefined;
+  /** Evaluated props passed to the model component. */
+  props: Record<string, unknown>;
+  /** The rule-engine action that placed this model into the scene. */
+  modelAction: {
+    /** Unique ID of the model action record. */
+    id: string;
+    /** ID of the model referenced by this action. */
+    modelId: string | number;
+    /** Props overrides defined on the action. */
+    props?: Record<string, unknown>;
+    /** ID of the slot this action targets. */
+    slotId?: string;
+    [key: string]: unknown;
+  };
+  /** The slot definition this instance was placed into. */
+  slotDefinition: SlotDefinition;
+  /** Recursively nested slot instances when the slotted model itself has slots. */
+  slots?: Record<string, SlotModelInstance[]>;
+}
+
+/**
+ * Props automatically injected into every `DynamicModel.component` at runtime.
+ * Extend this with your custom prop types: `DynamicModelComponentProps & { myProp: string }`.
+ */
+export interface DynamicModelComponentProps {
+  /**
+   * Resolved child model instances keyed by slot ID.
+   * Only present when the model has `slotDefinitions` and at least one slot is filled.
+   */
+  slots?: Record<string, SlotModelInstance[]>;
+  [key: string]: unknown;
+}
+
 // ─── Legacy types (unchanged) ────────────────────────────────────────────────
 
 export interface DynamicModel {
@@ -652,8 +772,18 @@ export interface DynamicModel {
   /**
    * Default prop values used when a new model action is created.
    * Each key matches a `propsDialog` key; values may be plain data or `{ expression: string }`.
+   * Include `slotDefinitions` here to declare named slots for child models.
    */
-  defaultProps: Record<string, ModelPropDefault>;
+  defaultProps: {
+    slotDefinitions?: SlotDefinition[];
+    [key: string]:
+      | string
+      | number
+      | boolean
+      | ModelPropDefault
+      | undefined
+      | SlotDefinition[];
+  };
   /** Optional tag used to group or filter models in the admin UI. */
   tag?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "k3-plugin-api",
-  "version": "1.2.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"
   }
-}
+}