@snaptrude/plugin-core 0.9.10 → 0.9.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snaptrude/plugin-core",
-  "version": "0.9.10",
+  "version": "0.9.12",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -16,17 +16,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "check-types": "tsc --noEmit",
-    "build": "tsup --clean",
-    "dev": "tsup --watch",
-    "clean-dist": "rm -rf dist",
-    "test": "node --test test/*.test.mjs",
-    "generate:manifest": "node scripts/generate-manifest.mjs",
-    "generate:manifest:check": "node scripts/generate-manifest.mjs --check",
-    "generate:manifest:all": "node scripts/generate-manifest.mjs --all",
-    "generate:manifest:all:check": "node scripts/generate-manifest.mjs --all --check"
-  },
   "devDependencies": {
     "ts-morph": "^28.0.0",
     "tsup": "^8.5.1",
@@ -37,5 +26,16 @@
   },
   "peerDependencies": {
     "zod": "^3.25.0 || ^4.0.0"
+  },
+  "scripts": {
+    "check-types": "tsc --noEmit",
+    "build": "tsup --clean",
+    "dev": "tsup --watch",
+    "clean-dist": "rm -rf dist",
+    "test": "node --test test/*.test.mjs",
+    "generate:manifest": "node scripts/generate-manifest.mjs",
+    "generate:manifest:check": "node scripts/generate-manifest.mjs --check",
+    "generate:manifest:all": "node scripts/generate-manifest.mjs --all",
+    "generate:manifest:all:check": "node scripts/generate-manifest.mjs --all --check"
   }
-}
+}

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
+>

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

@@ -4,9 +4,11 @@ import {
   BrepHandle,
   ComponentHandle,
   ContourHandle,
+  CurveHandle,
   ProfileHandle,
   Vec3Handle,
 } from "../../../handles"
+import { PluginGridStyleOptions } from "./grids"
 import {
   PluginSpaceType,
   PluginMassType,
@@ -628,6 +630,134 @@ export abstract class PluginDesignCreateApi {
     gridTag?: string,
   ): PluginApiReturn<ComponentHandle[]>
 
+  /**
+   * Create a free rectangular **structural grid** — one grid group with two
+   * perpendicular line families (`linesX` lines spaced `spacingX` apart, and
+   * `linesY` lines spaced `spacingY` apart) on the active storey. One undoable
+   * creation.
+   *
+   * Units: spacings in Snaptrude units; `angle` in degrees (CCW about +Y,
+   * default 0). Without `center` the grid is centred on the current viewport
+   * (the native tool's behavior) — pass `center` for deterministic placement.
+   *
+   * @param linesX - Line count of the first family (integer ≥ 1)
+   * @param linesY - Line count of the second family (integer ≥ 1)
+   * @param spacingX - First-family spacing (Snaptrude units, > 0)
+   * @param spacingY - Second-family spacing (Snaptrude units, > 0)
+   * @param options - `angle`, `center`, and {@linkcode PluginGridStyleOptions}
+   * @returns the created grid group's {@linkcode ComponentHandle}
+   *
+   * @examplePrompt Create a 5 by 8 structural grid with 6 metre spacing
+   * @examplePrompt Add a column grid rotated 30 degrees
+   * @examplePrompt Set up a structural grid at the site origin
+   *
+   * # Example
+   * ```ts
+   * const centre = await snaptrude.core.math.vec3.new(0, 0, 0)
+   * const grid = await snaptrude.design.create.grid(5, 8, 6, 6, { center: centre })
+   * ```
+   */
+  public abstract grid(
+    linesX: number,
+    linesY: number,
+    spacingX: number,
+    spacingY: number,
+    options?: {
+      angle?: number
+      center?: Vec3Handle
+    } & PluginGridStyleOptions,
+  ): PluginApiReturn<ComponentHandle>
+
+  /**
+   * Create a **structural grid from a single curve** — one grid group holding
+   * one wing with one line (the draw tool's output). The curve may be a line
+   * or an arc; circles are rejected with `VALIDATION`. Undoable.
+   *
+   * @param curve - The grid line's geometry ({@linkcode CurveHandle}, world space)
+   * @param options - `tag` (defaults to the draw tool's next tag) and
+   *   {@linkcode PluginGridStyleOptions}
+   * @returns the created grid group's {@linkcode ComponentHandle}
+   *
+   * @examplePrompt Draw a grid line from A to B
+   * @examplePrompt Add a curved grid line through these points
+   * @examplePrompt Create grid line "C" along this wall
+   *
+   * # Example
+   * ```ts
+   * const { vec3 } = snaptrude.core.math
+   * const from = await vec3.new(0, 0, 0)
+   * const to = await vec3.new(30, 0, 0)
+   * const curve = await snaptrude.core.geom.create.line(from, to)
+   * const grid = await snaptrude.design.create.gridFromCurve(curve, { tag: "A" })
+   * ```
+   */
+  public abstract gridFromCurve(
+    curve: CurveHandle,
+    options?: {
+      tag?: string
+    } & PluginGridStyleOptions,
+  ): PluginApiReturn<ComponentHandle>
+
+  /**
+   * Generate **structural grids fitted to mass footprints** — one grid group
+   * per footprint cluster, with counts and orientation derived from each
+   * footprint's geometry and the given spacings. All created groups commit as
+   * ONE undoable unit.
+   *
+   * Lenient like the native tool: masses without an extractable footprint
+   * (no B-rep, degenerate top face) are skipped; throws `VALIDATION` only when
+   * NONE of the given masses yields a footprint.
+   *
+   * @param masses - Masses whose footprints seat the grids
+   * @param spacingX - First-family spacing (Snaptrude units, > 0)
+   * @param spacingY - Second-family spacing (Snaptrude units, > 0)
+   * @param options - {@linkcode PluginGridStyleOptions}
+   * @returns the created grid groups' {@linkcode ComponentHandle}`[]`
+   *
+   * @examplePrompt Generate grids for the selected masses
+   * @examplePrompt Auto-generate a 6m structural grid on this building
+   * @examplePrompt Fit column grids to every mass on this storey
+   *
+   * # Example
+   * ```ts
+   * const masses = await snaptrude.design.query.listMasses({ storeys: [1] })
+   * const grids = await snaptrude.design.create.gridsFromMasses(masses, 6, 6)
+   * ```
+   */
+  public abstract gridsFromMasses(
+    masses: ComponentHandle[],
+    spacingX: number,
+    spacingY: number,
+    options?: PluginGridStyleOptions,
+  ): PluginApiReturn<ComponentHandle[]>
+
+  /**
+   * Create **columns at every grid-line intersection** of the given grid
+   * groups, sized `width` × `depth` and oriented to the grid axes, on the
+   * grids' storey. All columns commit as ONE undoable unit.
+   *
+   * @param grids - Grid groups whose intersections seat the columns
+   * @param width - Column width (Snaptrude units, > 0)
+   * @param depth - Column depth (Snaptrude units, > 0)
+   * @returns the created columns' {@linkcode ComponentHandle}`[]`
+   * @throws `VALIDATION` when an id does not resolve to a grid group;
+   *   `OPERATION_FAILED` when the grids have no line intersections
+   *
+   * @examplePrompt Generate columns on this grid
+   * @examplePrompt Place 450mm square columns at every grid intersection
+   *
+   * # Example
+   * ```ts
+   * const grids = await snaptrude.design.query.listGrids()
+   * const columns = await snaptrude.design.create.columnsFromGrids(grids, 0.45, 0.45)
+   * ```
+   */
+  public abstract columnsFromGrids(
+    grids: ComponentHandle[],
+    width: number,
+    depth: number,
+  ): PluginApiReturn<ComponentHandle[]>
+
   /**
    * Place a **furniture** item from the project library at a world position.
    *
@@ -1821,3 +1951,4 @@ export type PluginCreateSpaceItem = z.infer<typeof PluginCreateSpaceItem>
 
 export * from "./opening-fields"
 export * from "./bulk-items"
+export * from "./grids"