@snaptrude/plugin-core 0.9.17 → 0.9.18-voids-20261017.1

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

@@ -1,6 +1,13 @@
 import * as z from "zod"
-import { ContourHandle, ProfileHandle, Vec3Handle } from "../../../handles"
+import {
+  ComponentHandle,
+  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 +95,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 +103,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>
 
@@ -143,22 +152,23 @@ export type PluginCreateFloorItems = z.infer<typeof PluginCreateFloorItems>
 
 /**
  * One door to place via {@linkcode PluginDesignCreateApi.doors} — the same
- * fields as a `"door"` {@linkcode PluginDesignCreateOpeningOptions}, so the
- * size overrides singular {@linkcode PluginDesignCreateApi.door} lacks are
- * available per item. `facing` and `hinge` are WORLD POINTS, not directions:
- * `facing` on the side of the wall the door swings open to, `hinge` near the
- * jamb it is hinged on. Rejects unknown fields.
+ * fields as a `"door"` {@linkcode PluginDesignCreateOpeningOptions}.
+ * Values are evaluated before cutting. Numeric lengths use SU; unit strings
+ * are accepted in values. `facing` selects local +Z; `hinge` sets the declared
+ * hand enum (left = local -X, right = +X). Both are world points.
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `catalogId` | `string` | Library id: team `_id` or general `fullName` |
+ * | `familyId` | `string` | Hosted door family definition ID |
+ * | `version` | `number`? | Exact version; newest known by default |
+ * | `values` | `Record<string, number \| string>`? | Authored parameter overrides |
  * | `hostWall` | {@linkcode ComponentHandle} | The wall to host the door |
  * | `position` | {@linkcode Vec3Handle} | World point projected onto the wall |
  * | `facing` | {@linkcode Vec3Handle}? | World point on the side the door swings open to (default engine-chosen) |
- * | `hinge` | {@linkcode Vec3Handle}? | World point near the jamb the door is hinged on (default the catalog item's authored side) |
+ * | `hinge` | {@linkcode Vec3Handle}? | World point near the hinged jamb; requires hand control |
  * | `label` | `string`? | Instance name (optional) |
- * | `width` | `number`? | Width override (Snaptrude units, > 0; default the catalog item's) |
- * | `height` | `number`? | Height override (Snaptrude units, > 0; default the catalog item's) |
+ * | `width` | `number`? | Declared width parameter (SU, > 0), not evaluated hole width |
+ * | `height` | `number`? | Declared height parameter (SU, > 0) |
  */
 export const PluginCreateDoorItem = z
   .object({ ...PluginOpeningBaseOptions })
@@ -183,15 +193,17 @@ export type PluginCreateDoorItems = z.infer<typeof PluginCreateDoorItems>
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `catalogId` | `string` | Library id: team `_id` or general `fullName` |
+ * | `familyId` | `string` | Hosted window family definition ID |
+ * | `version` | `number`? | Exact version; newest known by default |
+ * | `values` | `Record<string, number \| string>`? | Authored parameter overrides; numeric lengths use SU |
  * | `hostWall` | {@linkcode ComponentHandle} | The wall to host the window |
  * | `position` | {@linkcode Vec3Handle} | World point projected onto the wall |
  * | `facing` | {@linkcode Vec3Handle}? | World point on the side the window opens to (default engine-chosen) |
- * | `hinge` | {@linkcode Vec3Handle}? | World point near the jamb the window is hinged on (default the catalog item's authored side) |
+ * | `hinge` | {@linkcode Vec3Handle}? | World point near the hinged jamb; requires hand control |
  * | `label` | `string`? | Instance name (optional) |
- * | `width` | `number`? | Width override (Snaptrude units, > 0; default the catalog item's) |
- * | `height` | `number`? | Height override (Snaptrude units, > 0; default the catalog item's) |
- * | `sillHeight` | `number`? | Wall base to window bottom (Snaptrude units, ≥ 0; default the catalog item's) |
+ * | `width` | `number`? | Declared width parameter (SU, > 0), not evaluated hole width |
+ * | `height` | `number`? | Declared height parameter (SU, > 0) |
+ * | `sillHeight` | `number`? | Declared sill parameter (SU, ≥ 0); position Y is ignored |
  */
 export const PluginCreateWindowItem = z
   .object({
@@ -252,3 +264,31 @@ export const PluginCreateFurnitureItems = z
 export type PluginCreateFurnitureItems = z.infer<
   typeof PluginCreateFurnitureItems
 >
+
+// ---------------------------------------------------------------------------
+// voids
+// ---------------------------------------------------------------------------
+
+/**
+ * One void to cut via {@linkcode PluginDesignCreateApi.voids} — the same fields as
+ * {@linkcode PluginDesignCreateApi.void}. Rejects unknown fields.
+ *
+ * | Property | Type | Description |
+ * | --- | --- | --- |
+ * | `host` | {@linkcode ComponentHandle} | The slab, floor, roof or ceiling to cut through. Not a wall. |
+ * | `outline` | {@linkcode ProfileHandle} | Closed, flat plan outline in world SU (all points at one height). That height is ignored: it is dropped straight onto the host's top face. |
+ */
+export const PluginCreateVoidItem = z
+  .object({
+    host: ComponentHandle,
+    outline: ProfileHandle,
+  })
+  .strict()
+export type PluginCreateVoidItem = z.infer<typeof PluginCreateVoidItem>
+
+/** The `items` array of {@linkcode PluginDesignCreateApi.voids} (1…1000; the host takes at most 200, 50 per host). */
+export const PluginCreateVoidItems = z
+  .array(PluginCreateVoidItem)
+  .min(1)
+  .max(PLUGIN_CREATE_BATCH_LIMIT)
+export type PluginCreateVoidItems = z.infer<typeof PluginCreateVoidItems>