@snaptrude/plugin-core 0.9.15 → 0.9.16-networks-20261008.1

package/src/api/design/create/bulk-items.ts

@@ -1,6 +1,8 @@
 import * as z from "zod"
 import { ContourHandle, ProfileHandle, Vec3Handle } from "../../../handles"
 import { PluginOpeningBaseOptions } from "./opening-fields"
+import { PluginWallType } from "../types"
+import { PluginFamilyValues } from "../catalog"
 
 /**
  * Maximum items per bulk `design.create.*` call. A bounded request keeps
@@ -88,7 +90,7 @@ export type PluginWallTopProfile = z.infer<typeof PluginWallTopProfile>
  * | `profile` | {@linkcode ProfileHandle} | Ordered curve chain (wall centerlines) |
  * | `height` | `number`? | Wall height (Snaptrude units, > 0; default engine default) |
  * | `thickness` | `number`? | Wall thickness (Snaptrude units, > 0; default: `wallType`'s total layer thickness when given, else engine default) |
- * | `wallType` | `string`? | Wall type name from `design.types.list("wall")` — layers/material/thickness defaults (default generic) |
+ * | `wallType` | {@linkcode PluginWallType}? | Legacy name/id or exact native `{ id, version }` pin from `design.types.list("wall")` (default generic) |
  * | `storey` | `number`? (int) | Target storey (must exist) — the run's walls are assigned + lifted to its base in the same undo entry (default: geometry-derived) |
  * | `topProfiles` | ({@linkcode PluginWallTopProfile} \| `null`)[]? | Top edge per curve of `profile`, same order; a `null` or missing entry keeps that wall flat at `height`. Raked / gabled walls (straight curves only) |
  */
@@ -96,9 +98,11 @@ export const PluginCreateWallRunItem = z.object({
   profile: ProfileHandle,
   height: z.number().optional(),
   thickness: z.number().optional(),
-  wallType: z.string().min(1).optional(),
+  wallType: PluginWallType.optional(),
   storey: z.number().int().optional(),
   topProfiles: z.array(PluginWallTopProfile.nullable()).optional(),
+  /** Optional family overrides in mm/degrees. Host length/height stay geometry inputs. */
+  values: PluginFamilyValues.optional(),
 })
 export type PluginCreateWallRunItem = z.infer<typeof PluginCreateWallRunItem>
 

package/src/api/design/create/index.ts

@@ -4,6 +4,7 @@ import {
   BrepHandle,
   ComponentHandle,
   ContourHandle,
+  LineHandle,
   CurveHandle,
   ProfileHandle,
   Vec3Handle,
@@ -29,6 +30,14 @@ import type {
   PluginCreateWindowItem,
 } from "./bulk-items"
 import { PluginWallTopProfile } from "./bulk-items"
+import { PluginWallType } from "../types"
+import {
+  PluginFamilyPlacement,
+  PluginFamilyFloorOptions,
+  PluginFamilySlabOptions,
+  PluginFamilyCeilingOptions,
+  PluginFamilyValues,
+} from "../catalog"
 
 /**
  * `design.create.*` — author new scene-committed BIM entities.
@@ -43,6 +52,12 @@ import { PluginWallTopProfile } from "./bulk-items"
  * Footprint objects take a {@linkcode ContourHandle} (outer profile + holes);
  * build one with `snaptrude.core.geom.create.contourFromProfile(s)`.
  *
+ * Family overloads take `{ type, values? }` from `design.catalog`. The family supplies
+ * construction; the contour or axis supplies instance geometry. Geometry uses SU,
+ * while family length overrides use mm and angles use degrees. Omitted parameters
+ * retain family defaults; shared/type, formula and geometry-bound overrides are refused.
+ * Placement never publishes a definition. Unsupported references or geometry fail before mutation.
+ *
  * `door`/`window` place a catalog item into a host wall (the world point is
  * projected onto the wall face to locate the opening; the wall is re-cut in one
  * undo entry) and throw if the point projects outside the wall. `smartLayout` is
@@ -219,20 +234,29 @@ export abstract class PluginDesignCreateApi {
    * ```
    */
   public abstract slab(
-    contour: ContourHandle,
-    thickness: number,
-    direction?: "up" | "down",
-    slabType?: PluginSlabType,
+    ...args:
+      | [
+          contour: ContourHandle,
+          thickness: number,
+          direction?: "up" | "down",
+          slabType?: PluginSlabType,
+        ]
+      | [contour: ContourHandle, options: PluginFamilySlabOptions]
   ): PluginApiReturn<ComponentHandle>
 
   /**
    * Create a **floor** by extruding a footprint contour by `thickness`
    * (extruded upward).
    *
+   * The native family overload takes `{ type, values?, position? }`. Contour
+   * geometry uses SU; family values use mm. The family supplies layer thickness.
+   * PG2 can split or merge the footprint, so both overloads return an array.
+   * A merge into an existing floor can return no newly created handles.
+   *
    * @param contour - Footprint (outer + holes)
    * @param thickness - Floor thickness (> 0)
    * @param position - Offset from origin
-   * @returns the {@linkcode ComponentHandle} of the created floor
+   * @returns Newly created {@linkcode ComponentHandle}s; an empty array after a merge
    * @throws if the contour is invalid or the thickness is not positive
    *
    * @examplePrompt Create a floor from this room outline
@@ -247,15 +271,15 @@ export abstract class PluginDesignCreateApi {
    * const floor = await snaptrude.design.create.floor(contour, 0.1)
    * ```
    *
-   * @performance For MORE THAN ONE floor, call `design.create.floors(items[])` — one
-   *   host round-trip and ONE undo entry for the whole batch. Looping this single-floor
-   *   creator is N round-trips and N undo entries.
+   * @performance For dimensional floors, `design.create.floors(items[])` uses one
+   *   host round-trip and one undo entry. That bulk method does not accept native
+   *   family options; use this method for a family-backed floor.
    */
   public abstract floor(
-    contour: ContourHandle,
-    thickness: number,
-    position?: Vec3Handle,
-  ): PluginApiReturn<ComponentHandle>
+    ...args:
+      | [contour: ContourHandle, thickness: number, position?: Vec3Handle]
+      | [contour: ContourHandle, options: PluginFamilyFloorOptions]
+  ): PluginApiReturn<ComponentHandle[]>
 
   /**
    * Create **many floors** in one undoable operation (bulk plural of
@@ -320,7 +344,7 @@ export abstract class PluginDesignCreateApi {
    */
   public abstract roof(
     contour: ContourHandle,
-    thickness: number,
+    thickness: number | PluginFamilyPlacement,
   ): PluginApiReturn<ComponentHandle>
 
   /**
@@ -346,9 +370,9 @@ export abstract class PluginDesignCreateApi {
    * ```
    */
   public abstract ceiling(
-    contour: ContourHandle,
-    thickness: number,
-    heightFromFloor?: number,
+    ...args:
+      | [contour: ContourHandle, thickness: number, heightFromFloor?: number]
+      | [contour: ContourHandle, options: PluginFamilyCeilingOptions]
   ): PluginApiReturn<ComponentHandle>
 
   /**
@@ -379,10 +403,14 @@ export abstract class PluginDesignCreateApi {
    * ```
    */
   public abstract column(
-    position: Vec3Handle,
-    crossSection: ContourHandle,
-    height: number,
-    directionUp?: Vec3Handle,
+    ...args:
+      | [
+          position: Vec3Handle,
+          crossSection: ContourHandle,
+          height: number,
+          directionUp?: Vec3Handle,
+        ]
+      | [axis: LineHandle, options: PluginFamilyPlacement]
   ): PluginApiReturn<ComponentHandle>
 
   /**
@@ -426,9 +454,9 @@ export abstract class PluginDesignCreateApi {
    * ```
    */
   public abstract beam(
-    section: ContourHandle,
-    length: number,
-    direction?: Vec3Handle,
+    ...args:
+      | [section: ContourHandle, length: number, direction?: Vec3Handle]
+      | [axis: LineHandle, options: PluginFamilyPlacement]
   ): PluginApiReturn<ComponentHandle>
 
   /**
@@ -439,12 +467,12 @@ export abstract class PluginDesignCreateApi {
    * @param height - Wall height (default engine default)
    * @param thickness - Wall thickness (default: the `wallType`'s total layer
    *   thickness when `wallType` is given, else the engine default)
-   * @param wallType - Wall type to build with — the same searchable list the
-   *   Draw tab's Wall Type dropdown offers. Pass a name from
-   *   `design.types.list("wall")` (the summary's `label`, or its `"wall:…"` id).
-   *   Drives the wall's construction layers and default material, and — when
-   *   `thickness` is omitted — its total layer thickness. Default: the engine's
-   *   generic wall.
+   * @param wallType - Legacy label/`wall:` id, or the exact `nativeFamily`
+   *   `{ id, version }` pin from `design.types.list("wall")`. Native pins are
+   *   authorized on every use; selecting a family in Draw is not registration.
+   *   Native pins support straight horizontal centerlines and flat tops only.
+   *   Omit thickness for native pins; a conflicting explicit thickness rejects.
+   *   Default: the engine's generic wall.
    * @param storey - Target storey (integer: `1` ground, `2` first floor, `-1`
    *   basement — same convention as `design.create.space`). The walls are
    *   assigned to it and lifted to its base elevation, all inside the same
@@ -503,9 +531,10 @@ export abstract class PluginDesignCreateApi {
     profile: ProfileHandle,
     height?: number,
     thickness?: number,
-    wallType?: string,
+    wallType?: PluginWallType,
     storey?: number,
     topProfiles?: (PluginWallTopProfile | null)[],
+    values?: PluginFamilyValues,
   ): PluginApiReturn<ComponentHandle[]>
 
   /**
@@ -1660,7 +1689,7 @@ export type PluginDesignCreateBeamArgs = z.infer<
  * | `profile` | {@linkcode ProfileHandle} | Ordered curve chain (wall centerlines) |
  * | `height` | `number`? | Wall height (default engine default) |
  * | `thickness` | `number`? | Wall thickness (default: `wallType`'s total layer thickness when given, else engine default) |
- * | `wallType` | `string`? | Wall type name from `design.types.list("wall")` — layers/material/thickness defaults (default generic) |
+ * | `wallType` | {@linkcode PluginWallType}? | Legacy name/id or exact native `{ id, version }` pin from `design.types.list("wall")` (default generic) |
  * | `storey` | `number`? | Target storey (integer, must exist) — walls assigned + lifted to its base in the same undo entry (default: geometry-derived) |
  * | `topProfiles` | ({@linkcode PluginWallTopProfile} \| `null`)[]? | Top edge per curve (same order); `null`/missing = flat at `height`. Straight curves only |
  */
@@ -1668,9 +1697,10 @@ export const PluginDesignCreateWallsArgs = z.object({
   profile: ProfileHandle,
   height: z.number().optional(),
   thickness: z.number().optional(),
-  wallType: z.string().min(1).optional(),
+  wallType: PluginWallType.optional(),
   storey: z.number().int().optional(),
   topProfiles: z.array(PluginWallTopProfile.nullable()).optional(),
+  values: PluginFamilyValues.optional(),
 })
 export type PluginDesignCreateWallsArgs = z.infer<
   typeof PluginDesignCreateWallsArgs