@snaptrude/plugin-core 0.10.0 → 1.0.0

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

@@ -0,0 +1,294 @@
+import * as z from "zod"
+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
+ * validation, command capture and rollback work finite; split a larger import
+ * into separate awaited batches, each with its own undo entry.
+ */
+export const PLUGIN_CREATE_BATCH_LIMIT = 1000
+
+// ---------------------------------------------------------------------------
+// wall top profile (raked / gabled walls)
+// ---------------------------------------------------------------------------
+
+/**
+ * One break point of a wall's top edge — see {@linkcode PluginWallTopProfile}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `along` | `number` | Position along the wall centerline as a fraction: `0` = start of the curve, `1` = end |
+ * | `height` | `number` | Top height above the wall base at that point (Snaptrude units, > 0) |
+ */
+export const PluginWallTopProfilePoint = z.object({
+  along: z.number().min(0).max(1),
+  height: z.number().positive(),
+})
+export type PluginWallTopProfilePoint = z.infer<
+  typeof PluginWallTopProfilePoint
+>
+
+/**
+ * The top edge of ONE wall as a polyline over its centerline: at least two
+ * points, `along` strictly increasing from `0` (curve start) to `1` (curve end),
+ * straight segments between them. Two points give a single slope (a raked
+ * wall), three give a gable, more give any stepped or folded ridge. Heights are
+ * measured from the wall base, like `height`. Both long faces follow the same
+ * profile, so the top stays a set of flat faces and the wall keeps its thickness
+ * end to end.
+ *
+ * Only straight centerlines take a top profile (an arc curve with one is
+ * rejected). A wall built this way is a real Wall — doors and windows host on
+ * it, corners mitre, quantities and Revit export read its geometry — but it is
+ * **non-parametric**: the parametric wall graph does not rebuild it, so a later
+ * move of a neighbour does not re-mitre its corner, exactly like a wall whose
+ * top edge was dragged by hand. `design.update.wall({ height })` scales it
+ * proportionally.
+ */
+export const PluginWallTopProfile = z
+  .array(PluginWallTopProfilePoint)
+  .min(2)
+  .superRefine((points, ctx) => {
+    if (points[0].along !== 0) {
+      ctx.addIssue({
+        code: "custom",
+        message: "topProfile must start at along = 0",
+      })
+    }
+    if (points[points.length - 1].along !== 1) {
+      ctx.addIssue({
+        code: "custom",
+        message: "topProfile must end at along = 1",
+      })
+    }
+    for (let i = 1; i < points.length; i++) {
+      if (points[i].along <= points[i - 1].along) {
+        ctx.addIssue({
+          code: "custom",
+          message:
+            "topProfile points must be in strictly increasing `along` order",
+        })
+        break
+      }
+    }
+  })
+export type PluginWallTopProfile = z.infer<typeof PluginWallTopProfile>
+
+// ---------------------------------------------------------------------------
+// wallRuns
+// ---------------------------------------------------------------------------
+
+/**
+ * One wall run to create via {@linkcode PluginDesignCreateApi.wallRuns} — the
+ * same inputs as {@linkcode PluginDesignCreateApi.walls}, one run per item.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `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` | {@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) |
+ */
+export const PluginCreateWallRunItem = z.object({
+  profile: ProfileHandle,
+  height: z.number().optional(),
+  thickness: z.number().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>
+
+/** The `items` array of {@linkcode PluginDesignCreateApi.wallRuns} (1…1000). */
+export const PluginCreateWallRunItems = z
+  .array(PluginCreateWallRunItem)
+  .min(1)
+  .max(PLUGIN_CREATE_BATCH_LIMIT)
+export type PluginCreateWallRunItems = z.infer<typeof PluginCreateWallRunItems>
+
+// ---------------------------------------------------------------------------
+// floors
+// ---------------------------------------------------------------------------
+
+/**
+ * One floor to create via {@linkcode PluginDesignCreateApi.floors} — the same
+ * footprint-extrude inputs as {@linkcode PluginDesignCreateApi.floor}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `contour` | {@linkcode ContourHandle} | Footprint (outer profile + holes) |
+ * | `thickness` | `number` | Floor thickness (Snaptrude units, > 0) |
+ * | `position` | {@linkcode Vec3Handle}? | Offset from origin (default origin) |
+ */
+export const PluginCreateFloorItem = z.object({
+  contour: ContourHandle,
+  thickness: z.number(),
+  position: Vec3Handle.optional(),
+})
+export type PluginCreateFloorItem = z.infer<typeof PluginCreateFloorItem>
+
+/** The `items` array of {@linkcode PluginDesignCreateApi.floors} (1…1000). */
+export const PluginCreateFloorItems = z
+  .array(PluginCreateFloorItem)
+  .min(1)
+  .max(PLUGIN_CREATE_BATCH_LIMIT)
+export type PluginCreateFloorItems = z.infer<typeof PluginCreateFloorItems>
+
+// ---------------------------------------------------------------------------
+// doors / windows
+// ---------------------------------------------------------------------------
+
+/**
+ * One door to place via {@linkcode PluginDesignCreateApi.doors} — the same
+ * 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 |
+ * |---|---|---|
+ * | `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 hinged jamb; requires hand control |
+ * | `label` | `string`? | Instance name (optional) |
+ * | `width` | `number`? | Declared width parameter (SU, > 0), not evaluated hole width |
+ * | `height` | `number`? | Declared height parameter (SU, > 0) |
+ */
+export const PluginCreateDoorItem = z
+  .object({ ...PluginOpeningBaseOptions })
+  .strict()
+export type PluginCreateDoorItem = z.infer<typeof PluginCreateDoorItem>
+
+/** The `items` array of {@linkcode PluginDesignCreateApi.doors} (1…1000). */
+export const PluginCreateDoorItems = z
+  .array(PluginCreateDoorItem)
+  .min(1)
+  .max(PLUGIN_CREATE_BATCH_LIMIT)
+export type PluginCreateDoorItems = z.infer<typeof PluginCreateDoorItems>
+
+/**
+ * One window to place via {@linkcode PluginDesignCreateApi.windows} — the same
+ * fields as a `"window"` {@linkcode PluginDesignCreateOpeningOptions}.
+ * `sillHeight` is a nonnegative Snaptrude-unit distance from the host wall's
+ * base to the BOTTOM of the window, not to its center. `facing` and `hinge`
+ * are WORLD POINTS, not directions: `facing` on the side of the wall the
+ * window opens to, `hinge` near the jamb it is hinged on. Rejects unknown
+ * fields.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `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 hinged jamb; requires hand control |
+ * | `label` | `string`? | Instance name (optional) |
+ * | `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({
+    ...PluginOpeningBaseOptions,
+    sillHeight: z.number().finite().nonnegative().optional(),
+  })
+  .strict()
+export type PluginCreateWindowItem = z.infer<typeof PluginCreateWindowItem>
+
+/** The `items` array of {@linkcode PluginDesignCreateApi.windows} (1…1000). */
+export const PluginCreateWindowItems = z
+  .array(PluginCreateWindowItem)
+  .min(1)
+  .max(PLUGIN_CREATE_BATCH_LIMIT)
+export type PluginCreateWindowItems = z.infer<typeof PluginCreateWindowItems>
+
+// ---------------------------------------------------------------------------
+// furnitureItems
+// ---------------------------------------------------------------------------
+
+/**
+ * One furniture instance to place via
+ * {@linkcode PluginDesignCreateApi.furnitureItems} — the same inputs as
+ * {@linkcode PluginDesignCreateApi.furniture} minus `createNewSourceMesh`: in a
+ * batch the host owns source-mesh persistence (a source is recorded once per
+ * call, however many items reuse it).
+ *
+ * `position.y` is the REST elevation: the item is grounded so its bounding-box
+ * base sits exactly at `position.y` (the same surface-flush contract as
+ * interactive drag-drop) — pass the floor/storey elevation to stand furniture
+ * on it; never add half the item's height yourself.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `catalogId` | `string` | Library id: team `_id` or general `fullName` |
+ * | `position` | {@linkcode Vec3Handle} | Absolute world placement point (`y` = rest elevation) |
+ * | `label` | `string`? | Instance name and readable label (default auto `${name}Ins${n}`) |
+ * | `angleInDegrees` | `number`? | Rotation about the vertical axis, in degrees (default unrotated) |
+ */
+export const PluginCreateFurnitureItem = z.object({
+  catalogId: z.string().min(1),
+  position: Vec3Handle,
+  label: z.string().optional(),
+  angleInDegrees: z.number().optional(),
+})
+export type PluginCreateFurnitureItem = z.infer<
+  typeof PluginCreateFurnitureItem
+>
+
+/**
+ * The `items` array of {@linkcode PluginDesignCreateApi.furnitureItems}
+ * (1…1000).
+ */
+export const PluginCreateFurnitureItems = z
+  .array(PluginCreateFurnitureItem)
+  .min(1)
+  .max(PLUGIN_CREATE_BATCH_LIMIT)
+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>

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

@@ -0,0 +1,137 @@
+import * as z from "zod"
+import { ComponentHandle, CurveHandle, Vec3Handle } from "../../../handles"
+
+// ---------------------------------------------------------------------------
+// Shared grid style vocabulary
+// ---------------------------------------------------------------------------
+
+/**
+ * Grid line style (mirrors the engine `LineMode` values verbatim — the same
+ * vocabulary as {@linkcode PluginReferenceLineStyle}).
+ */
+export const PluginGridLineStyle = z.enum(["SOLID", "DASHED", "DOT_DASH"])
+export type PluginGridLineStyle = z.infer<typeof PluginGridLineStyle>
+
+/**
+ * Optional visual styling shared by every grid creator (and reused as the
+ * patch shape by `design.update.grid`). All fields optional; engine defaults
+ * apply when omitted.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `style` | {@linkcode PluginGridLineStyle}? | Line style |
+ * | `weight` | `number`? | Line weight (> 0) |
+ * | `color` | `string`? | Line color as a `#rrggbb` hex string |
+ * | `showStart` | `boolean`? | Show the start-end tag bubble |
+ * | `showEnd` | `boolean`? | Show the end-end tag bubble |
+ */
+export const PluginGridStyleOptions = z.object({
+  style: PluginGridLineStyle.optional(),
+  weight: z.number().positive().optional(),
+  color: z
+    .string()
+    .regex(/^#[0-9a-fA-F]{6}$/, "color must be a #rrggbb hex string")
+    .optional(),
+  showStart: z.boolean().optional(),
+  showEnd: z.boolean().optional(),
+})
+export type PluginGridStyleOptions = z.infer<typeof PluginGridStyleOptions>
+
+// ---------------------------------------------------------------------------
+// create.grid — free rectangular grid
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.grid}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `linesX` | `number` | Line count of the first family (integer ≥ 1) |
+ * | `linesY` | `number` | Line count of the second family (integer ≥ 1) |
+ * | `spacingX` | `number` | Spacing of the first family (Snaptrude units, > 0) |
+ * | `spacingY` | `number` | Spacing of the second family (Snaptrude units, > 0) |
+ * | `angle` | `number`? | Rotation in degrees, CCW about +Y (default 0) |
+ * | `center` | {@linkcode Vec3Handle}? | Placement centre; defaults to the native viewport-centre behavior |
+ * | …style | {@linkcode PluginGridStyleOptions} | Optional line styling |
+ */
+export const PluginDesignCreateGridArgs = z
+  .object({
+    linesX: z.number().int().min(1),
+    linesY: z.number().int().min(1),
+    spacingX: z.number().positive().finite(),
+    spacingY: z.number().positive().finite(),
+    angle: z.number().finite().optional(),
+    center: Vec3Handle.optional(),
+  })
+  .merge(PluginGridStyleOptions)
+export type PluginDesignCreateGridArgs = z.infer<typeof PluginDesignCreateGridArgs>
+
+// ---------------------------------------------------------------------------
+// create.gridFromCurve — single-curve grid
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.gridFromCurve}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The grid line's geometry — a line or arc (circles are rejected) |
+ * | `tag` | `string`? | The line's grid tag (defaults to the draw tool's next tag) |
+ * | …style | {@linkcode PluginGridStyleOptions} | Optional line styling |
+ */
+export const PluginDesignCreateGridFromCurveArgs = z
+  .object({
+    curve: CurveHandle,
+    tag: z.string().min(1).optional(),
+  })
+  .merge(PluginGridStyleOptions)
+export type PluginDesignCreateGridFromCurveArgs = z.infer<
+  typeof PluginDesignCreateGridFromCurveArgs
+>
+
+// ---------------------------------------------------------------------------
+// create.gridsFromMasses — fitted grids
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.gridsFromMasses}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `masses` | {@linkcode ComponentHandle}`[]` | Masses whose footprints seat the grids |
+ * | `spacingX` | `number` | First-family spacing (Snaptrude units, > 0) |
+ * | `spacingY` | `number` | Second-family spacing (Snaptrude units, > 0) |
+ * | …style | {@linkcode PluginGridStyleOptions} | Optional line styling |
+ */
+export const PluginDesignCreateGridsFromMassesArgs = z
+  .object({
+    masses: z.array(ComponentHandle).min(1),
+    spacingX: z.number().positive().finite(),
+    spacingY: z.number().positive().finite(),
+  })
+  .merge(PluginGridStyleOptions)
+export type PluginDesignCreateGridsFromMassesArgs = z.infer<
+  typeof PluginDesignCreateGridsFromMassesArgs
+>
+
+// ---------------------------------------------------------------------------
+// create.columnsFromGrids — columns at line intersections
+// ---------------------------------------------------------------------------
+
+/**
+ * Arguments for {@linkcode PluginDesignCreateApi.columnsFromGrids}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `grids` | {@linkcode ComponentHandle}`[]` | Grid groups whose line intersections seat the columns |
+ * | `width` | `number` | Column width (Snaptrude units, > 0) |
+ * | `depth` | `number` | Column depth (Snaptrude units, > 0) |
+ */
+export const PluginDesignCreateColumnsFromGridsArgs = z.object({
+  grids: z.array(ComponentHandle).min(1),
+  width: z.number().positive().finite(),
+  depth: z.number().positive().finite(),
+})
+export type PluginDesignCreateColumnsFromGridsArgs = z.infer<
+  typeof PluginDesignCreateColumnsFromGridsArgs
+>