k3-plugin-api 1.4.5 → 1.6.0

package/README.md

@@ -13,7 +13,7 @@
 
 ## What is this package?
 
-`k3-plugin-api` contains the **TypeScript types** required to build K3 plugins — packages that extend the K3 configurator runtime with custom UI components, 3D models, pricing logic, and lifecycle hooks. The package ships zero runtime code; every export is a type, interface, or const enum.
+`k3-plugin-api` provides the **TypeScript types and runtime hooks** required to build K3 plugins — packages that extend the K3 configurator runtime with custom UI components, 3D models, pricing logic, and lifecycle hooks. It ships a thin runtime layer (reactive hooks like `useBOM()`, `useApp()`, etc.) that K3 injects at load time, plus all the type definitions for the plugin descriptor API.
 
 ---
 
@@ -41,14 +41,20 @@ const plugin: K3PluginDescriptor = {
   ui: {
     layout: {
       // wrap the default header with your own component
-      header: (Default) => (props) => <MyCustomHeader fallback={Default} {...props} />,
+      header: {
+        hoc: (Default) => (props) => <MyCustomHeader fallback={Default} {...props} />,
+        description: "Custom branded header",
+      },
     },
   },
 
   logic: {
     config: {
       // attach a custom order code to the configuration before it is persisted
-      onSave: (config) => ({ ...config, code: `TEST-${config.code}` }),
+      onSave: {
+        fn: (config) => ({ ...config, code: `TEST-${config.code}` }),
+        description: "Prepend TEST- to configuration code",
+      },
     },
   },
 };
@@ -64,35 +70,62 @@ 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.
+Plugins can access K3 configurator state at runtime using React hooks. These are automatically injected when the plugin is loaded via `init()`.
 
 ```ts
-import { useSettings, useBOM, usePrice } from "k3-plugin-api";
+import {
+  useK3PluginSettings,
+  useConfigurationVariables,
+  useConfigurationVariable,
+  useBOM,
+  useTotalPrice,
+  useFormattedTotalPrice,
+  useApp,
+  getSettings,
+} from "k3-plugin-api";
 
 const MyComponent = () => {
-  // Access plugin-specific settings
-  const settings = useSettings("acme.my-plugin");
-  
-  // Access current Bill-of-Materials
+  // Reactive plugin settings
+  const settings = useK3PluginSettings("acme.my-plugin") as { apiKey?: string };
+
+  // All configuration variables as a key-value map
+  const variables = useConfigurationVariables();
+
+  // Single variable by key
+  const color = useConfigurationVariable("color");
+
+  // Bill-of-Materials
   const bom = useBOM();
-  
-  // Access current total price
-  const price = usePrice();
-  
+
+  // Price (raw number or formatted string)
+  const price = useTotalPrice();
+  const formattedPrice = useFormattedTotalPrice();
+
+  // App metadata (product, subscription, etc.)
+  const app = useApp();
+
   return (
     <div>
       <p>API Key: {settings.apiKey}</p>
       <p>Total items: {bom.length}</p>
-      <p>Price: €{price}</p>
+      <p>Price: {formattedPrice}</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)
+Available hooks & functions:
+
+| Export                          | Description                                                                   |
+| ------------------------------- | ----------------------------------------------------------------------------- |
+| `getSettings(pluginId)`         | Non-reactive snapshot of plugin settings                                      |
+| `useK3PluginSettings(pluginId)` | Reactive hook — re-renders on settings change                                 |
+| `useConfigurationVariables()`   | All configuration variables as `Record<string, K3ConfigurationVariableEntry>` |
+| `useConfigurationVariable(key)` | Single variable value by its stable key                                       |
+| `useBOM()`                      | Current Bill-of-Materials (`K3BomEntry[]`)                                    |
+| `useTotalPrice()`               | Raw total price as `number`                                                   |
+| `useFormattedTotalPrice()`      | Locale-formatted price string (e.g. `"1.299,00 €"`)                           |
+| `useApp()`                      | App metadata (`K3AppInfo \| null`) — product, subscription, feature flags     |
 
 ### `settings` — Plugin Settings Component
 
@@ -120,6 +153,7 @@ const plugin: K3PluginDescriptor = {
 ```
 
 The `settings` component receives:
+
 - `settings: unknown` — The current settings object (initially `{}`)
 - `onSave: (settings: unknown) => void` — Callback to persist updated settings
 
@@ -187,18 +221,24 @@ const plugin: K3PluginDescriptor = {
 
 ## Key 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                                |
+| Type                           | Description                                                    |
+| ------------------------------ | -------------------------------------------------------------- |
+| `K3PluginDescriptor`           | Root descriptor object exported by a plugin                    |
+| `HOC<P>`                       | Higher-Order Component: `(Default: FC<P>) => FC<P>`            |
+| `HOCWithDescription`           | HOC + admin description (used in layout/dialog slots)          |
+| `CallbackWithDescription<T>`   | Logic callback + admin description                             |
+| `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                                 |
+| `K3ConfigurationVariables`     | Full variables map keyed by variable key                       |
+| `K3ConfigurationVariableEntry` | Single variable value (number, string, or simplified value)    |
+| `K3SimplifiedValue`            | Resolved value option (id, key, label, value, thumbnail)       |
+| `K3AppInfo`                    | App metadata (product, subscription, feature flags)            |
+| `K3FullApp`                    | Full app snapshot passed to `preprocessFullApp`                |
+| `VariableType`                 | Const enum of all variable types                               |
 
 ---
 

package/dist/index.cjs

@@ -0,0 +1,175 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region index.ts
+/**
+* Internal getter function injected by K3 at runtime.
+*/
+let _getSettings = null;
+/**
+* Internal reactive hook injected by K3 at runtime.
+*/
+let _usePluginSettings = null;
+/** @internal */
+let _useSelections = null;
+/** @internal */
+let _useSelectionByVariableKey = null;
+/** @internal */
+let _useBOM = null;
+/** @internal */
+let _useTotalPrice = null;
+/** @internal */
+let _useFormattedTotalPrice = null;
+/** @internal */
+let _useApp = null;
+/**
+* Get plugin-specific settings from the K3 store.
+* Returns a snapshot of the current settings - not reactive.
+* Use this in plugin components that need access to settings configured in the admin.
+*
+* @param pluginId - The unique plugin ID (e.g. "acme.my-plugin")
+* @returns The settings object for this plugin, or `{}` if none are configured
+*
+* @example
+* ```typescript
+* const settings = getSettings("acme.my-plugin") as { apiKey?: string };
+* if (settings.apiKey) {
+*   // Use API key
+* }
+* ```
+*/
+function getSettings(pluginId) {
+	if (!_getSettings) throw new Error("k3-plugin-api not initialized. Make sure K3 calls init() before using getSettings().");
+	return _getSettings(pluginId);
+}
+/**
+* Get plugin-specific settings from the K3 store as a reactive hook.
+* Re-renders the component whenever the settings change.
+* Use this in plugin React components.
+*
+* @param pluginId - The unique plugin ID (e.g. "acme.my-plugin")
+* @returns The settings object for this plugin, or `{}` if none are configured
+*
+* @example
+* ```typescript
+* const settings = useK3PluginSettings("acme.my-plugin") as { apiKey?: string };
+* ```
+*/
+function useK3PluginSettings(pluginId) {
+	if (!_usePluginSettings) throw new Error("k3-plugin-api not initialized. Make sure K3 calls init() before using useK3PluginSettings().");
+	return _usePluginSettings(pluginId);
+}
+/**
+* Reactive hook – returns all current configuration variables as a key-value map.
+* Keys are the variable's stable `key` string. Values are resolved (labels, not raw IDs).
+* Re-renders whenever any selection changes.
+*
+* @example
+* ```typescript
+* const variables = useConfigurationVariables();
+* const color = variables["color"] as K3SimplifiedValue;
+* ```
+*/
+function useConfigurationVariables() {
+	if (!_useSelections) throw new Error("k3-plugin-api not initialized. Make sure K3 calls init() before using useConfigurationVariables().");
+	return _useSelections();
+}
+/**
+* Reactive hook – returns the resolved value for a specific variable by its key,
+* or `undefined` if the variable has no active selection.
+*
+* @param variableKey - The stable key of the variable (as defined in the admin)
+*
+* @example
+* ```typescript
+* const width = useConfigurationVariable("width") as number;
+* const material = useConfigurationVariable("material") as K3SimplifiedValue;
+* ```
+*/
+function useConfigurationVariable(variableKey) {
+	if (!_useSelectionByVariableKey) throw new Error("k3-plugin-api not initialized. Make sure K3 calls init() before using useConfigurationVariable().");
+	return _useSelectionByVariableKey(variableKey);
+}
+/**
+* Reactive hook – returns the current Bill of Materials (Stückliste).
+* Re-renders whenever the BOM changes (i.e. on any selection change).
+*
+* @example
+* ```typescript
+* const bom = useBOM() as K3BomEntry[];
+* const total = bom.reduce((sum, e) => sum + e.price.price * e.qty, 0);
+* ```
+*/
+function useBOM() {
+	if (!_useBOM) throw new Error("k3-plugin-api not initialized. Make sure K3 calls init() before using useBOM().");
+	return _useBOM();
+}
+/**
+* Reactive hook – returns the current total price as a raw number.
+* Re-renders whenever the price changes.
+*/
+function useTotalPrice() {
+	if (!_useTotalPrice) throw new Error("k3-plugin-api not initialized. Make sure K3 calls init() before using useTotalPrice().");
+	return _useTotalPrice();
+}
+/**
+* Reactive hook – returns the current total price formatted as a locale string
+* (e.g. `"1.299,00 €"`), ready for display.
+* Re-renders whenever the price changes.
+*/
+function useFormattedTotalPrice() {
+	if (!_useFormattedTotalPrice) throw new Error("k3-plugin-api not initialized. Make sure K3 calls init() before using useFormattedTotalPrice().");
+	return _useFormattedTotalPrice();
+}
+/**
+* Reactive hook – returns the current K3 app metadata, including the booked
+* product identifier. Returns `null` while the app has not yet loaded.
+*
+* @example
+* ```typescript
+* const app = useApp() as K3AppInfo | null;
+* if (app?.product === "k3-pro") {
+*   // enable pro-only features
+* }
+* ```
+*/
+function useApp() {
+	if (!_useApp) throw new Error("k3-plugin-api not initialized. Make sure K3 calls init() before using useApp().");
+	return _useApp();
+}
+/**
+* Called by K3 when the plugin is loaded to inject runtime API functions.
+* @internal This function is called by K3 automatically - plugins should not call it directly.
+*/
+function init(api) {
+	_getSettings = api.getSettings;
+	_usePluginSettings = api.usePluginSettings;
+	_useSelections = api.useConfigurationVariables;
+	_useSelectionByVariableKey = api.useConfigurationVariable;
+	_useBOM = api.useBOM;
+	_useTotalPrice = api.useTotalPrice;
+	_useFormattedTotalPrice = api.useFormattedTotalPrice;
+	_useApp = api.useApp;
+}
+/** All variable type string literals. */
+const VariableType = {
+	List: "list",
+	Color: "color",
+	Number: "number",
+	Text: "text",
+	MultiSelect: "multiSelect",
+	Boolean: "boolean",
+	Image: "image",
+	Upload: "upload",
+	Components: "components",
+	Information: "information"
+};
+//#endregion
+exports.VariableType = VariableType;
+exports.getSettings = getSettings;
+exports.init = init;
+exports.useApp = useApp;
+exports.useBOM = useBOM;
+exports.useConfigurationVariable = useConfigurationVariable;
+exports.useConfigurationVariables = useConfigurationVariables;
+exports.useFormattedTotalPrice = useFormattedTotalPrice;
+exports.useK3PluginSettings = useK3PluginSettings;
+exports.useTotalPrice = useTotalPrice;