k3-plugin-api 1.2.0 → 1.3.0

package/index.ts

@@ -627,6 +627,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 +711,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.3.0",
   "description": "Official TypeScript types and plugin API for the K3 product configurator",
   "main": "index.js",
   "types": "index.ts",