@snaptrude/plugin-core 0.11.0-rc.1 → 1.0.0

package/src/api/design/grids.ts

@@ -0,0 +1,237 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { ComponentHandle } from "../../handles"
+import { PluginGridStyleOptions } from "./create/grids"
+
+/**
+ * Tag policy for structural line removal (mirrors the engine
+ * `GridLineTagPolicy` values verbatim): `"rewrite"` renumbers each affected
+ * wing's tag sequence after removal; `"preserve"` keeps the surviving lines'
+ * tags unchanged.
+ */
+export const PluginGridLineTagPolicy = z.enum(["rewrite", "preserve"])
+export type PluginGridLineTagPolicy = z.infer<typeof PluginGridLineTagPolicy>
+
+/** A positional grid-line address — indices into `design.query.grids.get`'s `wings` arrays. */
+export const PluginGridLineAddress = z.object({
+  wing: z.number().int().nonnegative(),
+  line: z.number().int().nonnegative(),
+})
+export type PluginGridLineAddress = z.infer<typeof PluginGridLineAddress>
+
+/**
+ * One per-wing entry of {@linkcode PluginDesignGridsApi.updateWings} —
+ * addressed by wing index. `spanMin`/`spanMax` move the family's length
+ * handles (Snaptrude units).
+ */
+export const PluginGridWingEntry = z.object({
+  wing: z.number().int().nonnegative(),
+  spacing: z.number().positive().finite().optional(),
+  count: z.number().int().min(1).optional(),
+  spanMin: z.number().finite().optional(),
+  spanMax: z.number().finite().optional(),
+})
+export type PluginGridWingEntry = z.infer<typeof PluginGridWingEntry>
+
+/** Arguments for {@linkcode PluginDesignGridsApi.updateWings}. */
+export const PluginDesignGridsUpdateWingsArgs = z.object({
+  grid: ComponentHandle,
+  wings: z.array(PluginGridWingEntry).min(1),
+})
+export type PluginDesignGridsUpdateWingsArgs = z.infer<
+  typeof PluginDesignGridsUpdateWingsArgs
+>
+
+/**
+ * One per-line entry of {@linkcode PluginDesignGridsApi.updateLines} —
+ * addressed positionally by `{ wing, line }` indices (invalidated by
+ * structural edits; re-query after mutating). `distanceToPrevious` /
+ * `distanceToNext` set the typed distance to the adjacent line on that side
+ * and are mutually exclusive.
+ *
+ * `visible` is **hide-only** (`false`), mirroring the product: per-line show
+ * does not exist — showing the GROUP (`design.visibility.show`) restores all
+ * of its lines, exactly like the native Show All.
+ */
+export const PluginGridLineEntry = z
+  .object({
+    wing: z.number().int().nonnegative(),
+    line: z.number().int().nonnegative(),
+    tag: z.string().min(1).optional(),
+    distanceToPrevious: z.number().positive().finite().optional(),
+    distanceToNext: z.number().positive().finite().optional(),
+    props: PluginGridStyleOptions.optional(),
+    visible: z.literal(false).optional(),
+  })
+  .superRefine((entry, ctx) => {
+    if (entry.distanceToPrevious !== undefined && entry.distanceToNext !== undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          "distanceToPrevious and distanceToNext are mutually exclusive on one line entry",
+      })
+    }
+  })
+export type PluginGridLineEntry = z.infer<typeof PluginGridLineEntry>
+
+/** Arguments for {@linkcode PluginDesignGridsApi.updateLines}. */
+export const PluginDesignGridsUpdateLinesArgs = z.object({
+  grid: ComponentHandle,
+  lines: z.array(PluginGridLineEntry).min(1),
+})
+export type PluginDesignGridsUpdateLinesArgs = z.infer<
+  typeof PluginDesignGridsUpdateLinesArgs
+>
+
+/** Arguments for {@linkcode PluginDesignGridsApi.addLine}. */
+export const PluginDesignGridsAddLineArgs = z.object({
+  grid: ComponentHandle,
+  wing: z.number().int().nonnegative(),
+  position: z.number().finite(),
+})
+export type PluginDesignGridsAddLineArgs = z.infer<typeof PluginDesignGridsAddLineArgs>
+
+/** Arguments for {@linkcode PluginDesignGridsApi.removeLines}. */
+export const PluginDesignGridsRemoveLinesArgs = z.object({
+  grid: ComponentHandle,
+  lines: z.array(PluginGridLineAddress).min(1),
+  tagPolicy: PluginGridLineTagPolicy.optional(),
+})
+export type PluginDesignGridsRemoveLinesArgs = z.infer<
+  typeof PluginDesignGridsRemoveLinesArgs
+>
+
+/**
+ * `design.grids.*` — structural edits on a grid's line structure (the
+ * entity-family home for grid-specific operations, like `design.doors`).
+ *
+ * Lines are addressed positionally as `{ wing, line }` index pairs into the
+ * `wings` arrays returned by `design.query.grids.get`. Adding, removing, or
+ * re-counting lines re-indexes the wing — re-query after every structural edit.
+ *
+ * Group-level edits (default styling, angle, storey visibility) live on
+ * `design.update.grid`; creation lives on `design.create.grid*`.
+ *
+ * Accessed via `snaptrude.design.grids`.
+ */
+export abstract class PluginDesignGridsApi {
+  constructor() {}
+
+  /**
+   * Update one or more **wings** of a grid with sparse per-wing entries —
+   * `spacing` (uniform re-space), `count` (grow/truncate + tag renumber),
+   * `spanMin`/`spanMax` (family length handles). Every change routes through
+   * the exact setters the native panel uses — each changed field commits its
+   * own undoable command, identical to editing that field in the panel.
+   *
+   * A `count` change re-indexes the wing's lines — positional `{ wing, line }`
+   * addresses held from before the call are stale afterwards; re-query.
+   *
+   * @param grid - The grid group
+   * @param wings - Sparse {@linkcode PluginGridWingEntry} entries (≥ 1)
+   * @returns `true` once applied
+   *
+   * @examplePrompt Change this grid's spacing to 8 metres
+   * @examplePrompt Make this grid 10 by 12 lines
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.design.grids.updateWings(grid, [{ wing: 0, spacing: 8, count: 10 }])
+   * ```
+   */
+  public abstract updateWings(
+    grid: ComponentHandle,
+    wings: PluginGridWingEntry[],
+  ): PluginApiReturn<boolean>
+
+  /**
+   * Update one or more **lines** of a grid with sparse per-line entries —
+   * `tag`, `distanceToPrevious`/`distanceToNext` (typed distance to the
+   * neighbour on that side; mutually exclusive), `props` (per-line style
+   * overrides), and `visible: false` (hide). Every change routes through the
+   * exact setters the native panel uses — each changed field commits its own
+   * undoable command, identical to editing that field in the panel.
+   *
+   * Visibility mirrors the product exactly: `visible` accepts only `false` —
+   * per-line show does not exist. Hiding lines that would leave NO visible
+   * line hides the whole GROUP instead (the native last-line rule; those line
+   * flags stay untouched). To bring hidden lines back, show the group
+   * (`design.visibility.show([grid])`) — it restores ALL of its lines, like
+   * the native Show All.
+   *
+   * @param grid - The grid group
+   * @param lines - Sparse {@linkcode PluginGridLineEntry} entries (≥ 1)
+   * @returns `true` once applied
+   *
+   * @examplePrompt Rename grid line 2 to "B"
+   * @examplePrompt Move this grid line 4 metres from its neighbour
+   * @examplePrompt Hide grid line 3 on this grid
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.design.grids.updateLines(grid, [
+   *   { wing: 0, line: 1, tag: "B", distanceToPrevious: 4 },
+   * ])
+   * ```
+   */
+  public abstract updateLines(
+    grid: ComponentHandle,
+    lines: PluginGridLineEntry[],
+  ): PluginApiReturn<boolean>
+
+  /**
+   * Insert a parallel grid line into a wing at an explicit position along the
+   * wing's spacing axis (Snaptrude units, wing-local — line 0's position can
+   * be read from its curve). Sibling lines do not shift; the wing's tag
+   * sequence is renumbered. Undoable.
+   *
+   * @param grid - The grid group
+   * @param wing - Wing index
+   * @param position - Position along the wing's spacing axis (Snaptrude units)
+   * @returns `true` once inserted
+   * @throws `VALIDATION` on a bad wing index or non-finite position
+   *
+   * @examplePrompt Add a grid line between lines 2 and 3
+   * @examplePrompt Insert an extra grid line 4 metres from line A
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.design.grids.addLine(grid, 0, 12.5)
+   * ```
+   */
+  public abstract addLine(
+    grid: ComponentHandle,
+    wing: number,
+    position: number,
+  ): PluginApiReturn<boolean>
+
+  /**
+   * Remove grid lines by positional address, as ONE undoable step. With
+   * `tagPolicy: "rewrite"` (default) each affected wing renumbers its tag
+   * sequence; `"preserve"` keeps surviving tags unchanged. A wing emptied of
+   * lines is dropped from the group.
+   *
+   * Removing EVERY line of the group is rejected — delete the group instead
+   * (`design.delete.entities`).
+   *
+   * @param grid - The grid group
+   * @param lines - Positional addresses to remove (see `design.query.grids.get`)
+   * @param tagPolicy - `"rewrite"` (default) or `"preserve"`
+   * @returns `true` once removed
+   * @throws `VALIDATION` on out-of-range addresses; `OPERATION_FAILED` when the
+   *   removal would delete the group's last line
+   *
+   * @examplePrompt Delete grid line B
+   * @examplePrompt Remove the last two lines of this grid without renumbering
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.design.grids.removeLines(grid, [{ wing: 0, line: 2 }], "preserve")
+   * ```
+   */
+  public abstract removeLines(
+    grid: ComponentHandle,
+    lines: PluginGridLineAddress[],
+    tagPolicy?: PluginGridLineTagPolicy,
+  ): PluginApiReturn<boolean>
+}

package/src/api/design/index.ts

@@ -14,8 +14,18 @@ import { PluginDesignTransformApi } from "./transform"
 import { PluginDesignEditApi } from "./edit"
 import { PluginDesignUpdateApi } from "./update"
 import { PluginDesignVisibilityApi } from "./visibility"
+import { PluginDesignDimensionsApi } from "./dimensions"
 import { PluginDesignTypesApi } from "./types"
+import { PluginDesignFamilyApi } from "./family"
+import { PluginDesignGridsApi } from "./grids"
+import { PluginDesignCatalogApi } from "./catalog"
+import { PluginDesignBimApi } from "./bim"
 import { PluginDesignChangeResult } from "./lock"
+import {
+  PluginElectricalApi,
+  PluginPlumbingApi,
+  PluginMechanicalApi,
+} from "./networks"
 
 /**
  * `snaptrude.design.*` — author, query & edit BIM geometry.
@@ -30,7 +40,9 @@ import { PluginDesignChangeResult } from "./lock"
  * - {@linkcode PluginDesignApi.erase} — plan-level adjacency-edge erase (NOT hard delete)
  * - {@linkcode PluginDesignApi.delete} — hard entity removal
  * - {@linkcode PluginDesignApi.visibility} — hide / isolate / reveal entities
+ * - {@linkcode PluginDesignApi.dimensions} — dimension lines (Measuring Tape): create / list / delete / hide
  * - {@linkcode PluginDesignApi.types} — read-only building type / assembly reference
+ * - {@linkcode PluginDesignApi.family} — author parametric families from a JSON spec
  * - {@linkcode PluginDesignApi.lock} / {@linkcode PluginDesignApi.unlock} / {@linkcode PluginDesignApi.isLocked} / {@linkcode PluginDesignApi.listLocked} — lock state (top-level design verbs, §2A.1)
  * - {@linkcode PluginDesignApi.lockArea} / {@linkcode PluginDesignApi.unlockArea} / {@linkcode PluginDesignApi.isAreaLocked} / {@linkcode PluginDesignApi.listAreaLocked} — footprint-area lock for Room/Department spaces
  *
@@ -65,8 +77,27 @@ export abstract class PluginDesignApi {
   public abstract update: PluginDesignUpdateApi
   /** Hide / isolate / reveal entities. See {@linkcode PluginDesignVisibilityApi}. */
   public abstract visibility: PluginDesignVisibilityApi
+  /** Dimension lines (Measuring Tape). See {@linkcode PluginDesignDimensionsApi}. */
+  public abstract dimensions: PluginDesignDimensionsApi
   /** Read-only building type / assembly reference. See {@linkcode PluginDesignTypesApi}. */
   public abstract types: PluginDesignTypesApi
+  /** Author parametric families from a JSON spec. See {@linkcode PluginDesignFamilyApi}. */
+  public abstract family: PluginDesignFamilyApi
+  /** Shared family and asset inventory, including supported placement and update paths. */
+  public abstract catalog: PluginDesignCatalogApi
+
+  /** Agent-driven Sketch-to-BIM with explicit per-edge constructions. */
+  public abstract bim: PluginDesignBimApi
+
+  /** Structural edits on a grid's line structure. See {@linkcode PluginDesignGridsApi}. */
+  public abstract grids: PluginDesignGridsApi
+
+  /** Persistent electrical equipment, routes and circuit graphs. */
+  public abstract electrical: PluginElectricalApi
+  /** Persistent plumbing equipment and directed pipe graphs. */
+  public abstract plumbing: PluginPlumbingApi
+  /** Persistent family-backed HVAC ducts, fittings and equipment. */
+  public abstract mechanical: PluginMechanicalApi
 
   /**
    * Lock entities so they cannot be edited. Undoable. Cascades to void/door/window
@@ -88,7 +119,9 @@ export abstract class PluginDesignApi {
    * // affected is post-cascade: hosted doors/windows are included
    * ```
    */
-  public abstract lock(components: ComponentHandle[]): PluginApiReturn<PluginDesignChangeResult>
+  public abstract lock(
+    components: ComponentHandle[],
+  ): PluginApiReturn<PluginDesignChangeResult>
 
   /**
    * Unlock previously locked entities so they can be edited again. Undoable.
@@ -108,7 +141,9 @@ export abstract class PluginDesignApi {
    * const { affected } = await snaptrude.design.unlock(locked)
    * ```
    */
-  public abstract unlock(components: ComponentHandle[]): PluginApiReturn<PluginDesignChangeResult>
+  public abstract unlock(
+    components: ComponentHandle[],
+  ): PluginApiReturn<PluginDesignChangeResult>
 
   /**
    * Test whether an entity is locked (folds group + bucket lock unless `includeInherited: false`).
@@ -176,7 +211,9 @@ export abstract class PluginDesignApi {
    * console.log("area-locked", affected.length, "spaces")
    * ```
    */
-  public abstract lockArea(spaces: ComponentHandle[]): PluginApiReturn<PluginDesignChangeResult>
+  public abstract lockArea(
+    spaces: ComponentHandle[],
+  ): PluginApiReturn<PluginDesignChangeResult>
 
   /**
    * Unlock the footprint area of previously area-locked spaces so their area can
@@ -197,7 +234,9 @@ export abstract class PluginDesignApi {
    * const { affected } = await snaptrude.design.unlockArea(locked)
    * ```
    */
-  public abstract unlockArea(spaces: ComponentHandle[]): PluginApiReturn<PluginDesignChangeResult>
+  public abstract unlockArea(
+    spaces: ComponentHandle[],
+  ): PluginApiReturn<PluginDesignChangeResult>
 
   /**
    * Test whether a space's footprint area is locked. A read — never throws;
@@ -256,4 +295,10 @@ export * from "./transform"
 export * from "./edit"
 export * from "./update"
 export * from "./visibility"
+export * from "./dimensions"
 export * from "./types"
+export * from "./family"
+export * from "./grids"
+export * from "./networks"
+export * from "./catalog"
+export * from "./bim"