@snaptrude/plugin-core 0.9.9 → 0.9.11

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

@@ -0,0 +1,197 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { CurveHandle, BBoxComponents } from "../../../handles"
+import { PluginReferenceLineStyle } from "../create"
+
+// ---------------------------------------------------------------------------
+// Records
+// ---------------------------------------------------------------------------
+
+/**
+ * Visual properties of grid lines — the group's defaults and any per-line
+ * overrides share this shape (values mirror the engine's `GridLineProps`).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `style` | {@linkcode PluginReferenceLineStyle} | Line style (`"SOLID"` \| `"DASHED"` \| `"DOT_DASH"`) |
+ * | `weight` | `number` | Line weight |
+ * | `color` | `string` | Line color as a `#rrggbb` hex string |
+ * | `showStart` | `boolean` | Whether the start-end tag bubble is shown |
+ * | `showEnd` | `boolean` | Whether the end-end tag bubble is shown |
+ */
+export const PluginGridLineProps = z.object({
+  style: PluginReferenceLineStyle,
+  weight: z.number(),
+  color: z.string(),
+  showStart: z.boolean(),
+  showEnd: z.boolean(),
+})
+export type PluginGridLineProps = z.infer<typeof PluginGridLineProps>
+
+/**
+ * One grid line within a wing.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The line's geometry in **world space** (a line or arc; read coordinates via `core.geom.curve`) |
+ * | `tag` | `string` | The line's grid tag (e.g. `"A"`, `"3"`) |
+ * | `visible` | `boolean` | Persisted per-line visibility |
+ * | `props` | {@linkcode PluginGridLineProps} | **Effective** visual properties (group defaults merged with this line's overrides) |
+ * | `overrides` | `Partial<`{@linkcode PluginGridLineProps}`>`? | This line's raw overrides, when any exist |
+ */
+export const PluginGridLineRecord = z.object({
+  curve: CurveHandle,
+  tag: z.string(),
+  visible: z.boolean(),
+  props: PluginGridLineProps,
+  overrides: PluginGridLineProps.partial().optional(),
+})
+export type PluginGridLineRecord = z.infer<typeof PluginGridLineRecord>
+
+/**
+ * One wing of a grid — a family of parallel lines sharing a local frame.
+ * `spacing` and `span` are measured along the wing's local axes in
+ * Snaptrude units; line addresses used by mutating APIs are
+ * `{ wing, line }` index pairs into these arrays.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spacing` | `number` | Nominal spacing between adjacent lines (Snaptrude units) |
+ * | `tagStart` | `string` | First tag of the wing's deterministic tag sequence |
+ * | `span` | `{ min: number; max: number }`? | Explicit family length along the wing's line axis, when baked |
+ * | `lines` | {@linkcode PluginGridLineRecord}`[]` | The wing's lines, in wing order (index = the `line` address) |
+ */
+export const PluginGridWingRecord = z.object({
+  spacing: z.number(),
+  tagStart: z.string(),
+  span: z.object({ min: z.number(), max: z.number() }).optional(),
+  lines: z.array(PluginGridLineRecord),
+})
+export type PluginGridWingRecord = z.infer<typeof PluginGridWingRecord>
+
+/**
+ * Per-storey 2D-plan visibility of a grid.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `activeStorey` | `number` | The storey the grid belongs to |
+ * | `disabledOnStoreys` | `number[]` | Storeys on whose 2D plan the grid is hidden |
+ */
+export const PluginGridStoreyVisibility = z.object({
+  activeStorey: z.number(),
+  disabledOnStoreys: z.array(z.number()),
+})
+export type PluginGridStoreyVisibility = z.infer<typeof PluginGridStoreyVisibility>
+
+// ---------------------------------------------------------------------------
+// get — args & result
+// ---------------------------------------------------------------------------
+
+/**
+ * Property names readable via {@linkcode PluginDesignQueryGridsApi.get}.
+ *
+ * | Value | Description |
+ * |---|---|
+ * | `"angle"` | World rotation about +Y, in **degrees** |
+ * | `"props"` | Group-level default line properties |
+ * | `"storeyVisibility"` | Active storey + storeys where the grid is hidden in 2D |
+ * | `"wings"` | Full wing/line structure with world-space curve handles |
+ * | `"bounds"` | World-space axis-aligned bounding box of the grid geometry |
+ */
+export const PluginGridGetProperty = z.enum([
+  "angle",
+  "props",
+  "storeyVisibility",
+  "wings",
+  "bounds",
+])
+export type PluginGridGetProperty = z.infer<typeof PluginGridGetProperty>
+
+/**
+ * Arguments for {@linkcode PluginDesignQueryGridsApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `gridId` | `string` | The grid group ID to query |
+ * | `properties` | {@linkcode PluginGridGetProperty}`[]` | Properties to retrieve |
+ */
+export const PluginGridGetArgs = z.object({
+  gridId: z.string(),
+  properties: z.array(PluginGridGetProperty),
+})
+export type PluginGridGetArgs = z.infer<typeof PluginGridGetArgs>
+
+/**
+ * Result of {@linkcode PluginDesignQueryGridsApi.get} — only the requested
+ * properties are present.
+ */
+export const PluginGridGetResult = z
+  .object({
+    angle: z.number(),
+    props: PluginGridLineProps,
+    storeyVisibility: PluginGridStoreyVisibility,
+    wings: z.array(PluginGridWingRecord),
+    bounds: BBoxComponents,
+  })
+  .partial()
+export type PluginGridGetResult = z.infer<typeof PluginGridGetResult>
+
+// ---------------------------------------------------------------------------
+// Abstract API
+// ---------------------------------------------------------------------------
+
+/**
+ * `design.query.grids.*` — structural-grid-specific reads.
+ *
+ * A **grid** (grid group) is a structural/documentation grid: one or more
+ * *wings* (families of parallel lines with a shared local frame), each holding
+ * tagged grid *lines* (straight lines, or a lone arc). Enumerate grids with
+ * `design.query.listGrids`; read an individual grid's structure here.
+ *
+ * Lines have no stable identity of their own — mutating APIs address them
+ * positionally as `{ wing, line }` index pairs into the `wings` arrays
+ * returned by {@linkcode get}. Structural edits (adding/removing lines,
+ * count changes) re-index lines; re-query after mutating.
+ *
+ * Accessed via `snaptrude.design.query.grids`.
+ */
+export abstract class PluginDesignQueryGridsApi {
+  constructor() {}
+
+  /**
+   * Get properties of a grid by its ID.
+   *
+   * Only the properties listed in `properties` are returned — unlisted
+   * properties will be `undefined` in the result. `wings` is the heavy
+   * read (it registers a world-space {@linkcode CurveHandle} per line);
+   * request it only when the geometry is needed.
+   *
+   * Units: `angle` is in **degrees** (positive = CCW about +Y); `spacing`,
+   * `span`, `bounds`, and curve coordinates are in **Snaptrude units**,
+   * world space.
+   *
+   * @param gridId - The unique grid group ID
+   * @param properties - Array of property names to retrieve. See
+   *   {@linkcode PluginGridGetProperty}.
+   * @returns A partial {@linkcode PluginGridGetResult} containing only the
+   *   requested properties
+   * @throws If the grid does not exist
+   *
+   * @examplePrompt What is the spacing of this grid?
+   * @examplePrompt Read the grid line tags on this structural grid
+   * @examplePrompt Get the geometry of every line in this grid
+   * @examplePrompt Which storeys is this grid hidden on?
+   *
+   * # Example
+   * ```ts
+   * const [grid] = await snaptrude.design.query.listGrids()
+   * const { wings } = await snaptrude.design.query.grids.get(grid, ["wings"])
+   * // wings[0].lines[0].curve is an opaque CurveHandle in world space;
+   * // read its coordinates via `snaptrude.core.geom.curve`.
+   * ```
+   */
+  public abstract get(
+    gridId: string,
+    properties: z.infer<typeof PluginGridGetProperty>[],
+  ): PluginApiReturn<PluginGridGetResult>
+}

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

@@ -11,6 +11,7 @@ import { PluginStaircasePreset } from "../create"
 import { PluginDesignQueryGeometryApi } from "./geometry"
 import { PluginDesignQuerySpacesApi } from "./spaces"
 import { PluginDesignQueryReferenceLinesApi } from "./referenceLines"
+import { PluginDesignQueryGridsApi } from "./grids"
 
 // ---------------------------------------------------------------------------
 // Entity type vocabulary
@@ -41,6 +42,7 @@ import { PluginDesignQueryReferenceLinesApi } from "./referenceLines"
  * | `"curtainWall"` | Parametric curtain wall |
  * | `"mullion"` | Curtain-wall mullion |
  * | `"panel"` | Curtain-wall panel |
+ * | `"grid"` | Structural grid group |
  */
 export const PluginEntityType = z.enum([
   "wall",
@@ -60,6 +62,7 @@ export const PluginEntityType = z.enum([
   "curtainWall",
   "mullion",
   "panel",
+  "grid",
 ])
 export type PluginEntityType = z.infer<typeof PluginEntityType>
 
@@ -304,6 +307,8 @@ export abstract class PluginDesignQueryApi {
   public abstract spaces: PluginDesignQuerySpacesApi
   /** Reference-line-specific reads. See {@linkcode PluginDesignQueryReferenceLinesApi}. */
   public abstract referenceLines: PluginDesignQueryReferenceLinesApi
+  /** Structural-grid-specific reads. See {@linkcode PluginDesignQueryGridsApi}. */
+  public abstract grids: PluginDesignQueryGridsApi
 
   constructor() {}
 
@@ -721,6 +726,27 @@ export abstract class PluginDesignQueryApi {
     filter?: PluginEntityFilter,
   ): PluginApiReturn<ComponentHandle[]>
 
+  /**
+   * List all the structural grids (grid groups) in the project, optionally
+   * filtered by storey, building, selection state, or region.
+   *
+   * @param filter - an optional {@linkcode PluginEntityFilter}
+   * @returns grid-group {@linkcode ComponentHandle}`[]`
+   *
+   * @examplePrompt List all the structural grids in the model
+   * @examplePrompt How many grids are on the ground floor?
+   * @examplePrompt Show the grids on this storey
+   * @examplePrompt Which grids are currently selected?
+   *
+   * # Example
+   * ```ts
+   * const groundFloorGrids = await snaptrude.design.query.listGrids({ storeys: [1] })
+   * ```
+   */
+  public abstract listGrids(
+    filter?: PluginEntityFilter,
+  ): PluginApiReturn<ComponentHandle[]>
+
   // ── single-entity access & identity ─────────────────────────────────────────
 
   /**
@@ -1145,3 +1171,4 @@ export type PluginStoreyOutlineResult = z.infer<
 export * from "./geometry"
 export * from "./spaces"
 export * from "./referenceLines"
+export * from "./grids"

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

@@ -15,6 +15,7 @@ import {
   PluginBuildableEnvelopeVerticalCap,
   PluginBuildableEnvelopeUpdateResult,
 } from "../../entity/buildableEnvelope"
+import { PluginGridStyleOptions } from "../create/grids"
 
 /**
  * Sparse property updates for a space. Only provided fields change.
@@ -238,6 +239,27 @@ export type PluginDesignSetStoreyArgs = z.infer<
   typeof PluginDesignSetStoreyArgs
 >
 
+/**
+ * The sparse GROUP-LEVEL patch accepted by {@linkcode PluginDesignUpdateApi.grid}.
+ * Only provided fields change. Wing- and line-level updates live on the grids
+ * entity family: `design.grids.updateWings` / `design.grids.updateLines`.
+ */
+export const PluginGridPatch = z.object({
+  angle: z.number().finite().optional(),
+  props: PluginGridStyleOptions.optional(),
+  storeyVisibility: z
+    .array(z.object({ storey: z.number().int(), visible: z.boolean() }))
+    .optional(),
+})
+export type PluginGridPatch = z.infer<typeof PluginGridPatch>
+
+/** Arguments for {@linkcode PluginDesignUpdateApi.grid}. */
+export const PluginDesignUpdateGridArgs = z.object({
+  grid: ComponentHandle,
+  patch: PluginGridPatch,
+})
+export type PluginDesignUpdateGridArgs = z.infer<typeof PluginDesignUpdateGridArgs>
+
 /**
  * `snaptrude.design.update` — edit existing scene entities (properties + geometry).
  *
@@ -290,6 +312,37 @@ export abstract class PluginDesignUpdateApi {
     label: string,
   ): PluginApiReturn<boolean>
 
+  /**
+   * Update a structural grid's **group-level** fields with a sparse patch —
+   * default line styling, absolute angle, and per-storey 2D visibility. Only
+   * provided fields change. Wing- and line-level updates live on the grids
+   * entity family: {@linkcode PluginDesignGridsApi.updateWings} /
+   * {@linkcode PluginDesignGridsApi.updateLines}.
+   *
+   * 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. `angle` is an absolute target in degrees (CCW
+   * about +Y).
+   *
+   * @param grid - The grid group to update
+   * @param patch - The sparse {@linkcode PluginGridPatch}
+   * @returns `true` once applied
+   *
+   * @examplePrompt Rotate the grid to 45 degrees
+   * @examplePrompt Make this grid's lines dashed and grey
+   * @examplePrompt Hide this grid on storey 3's plan
+   *
+   * # Example
+   * ```ts
+   * const [grid] = await snaptrude.design.query.listGrids()
+   * await snaptrude.design.update.grid(grid, { angle: 45, props: { style: "DASHED" } })
+   * ```
+   */
+  public abstract grid(
+    grid: ComponentHandle,
+    patch: PluginGridPatch,
+  ): PluginApiReturn<boolean>
+
   /**
    * Update a single space (room) — change its properties (room label, space
    * type, mass type, area class, department) and/or replace its geometry by

package/src/api/workspace/index.ts

@@ -10,13 +10,16 @@ import { PluginApiReturn } from "../../types"
  * Teams are **read-only** here (no create/invite/delete in v1, a deliberate
  * safety decision); there are no folders in v1. A `projectId` is the project's
  * floorkey. Plan limits are enforced by the backend — a limit rejection surfaces
- * as a normal host error. It also carries the workspace-level mode switch for
+ * as a normal host error. It also carries the workspace-level mode switches for
  * Present mode ({@linkcode PluginWorkspaceApi.openPresentMode} /
- * {@linkcode PluginWorkspaceApi.closePresentMode}).
+ * {@linkcode PluginWorkspaceApi.closePresentMode}) and Program mode
+ * ({@linkcode PluginWorkspaceApi.openProgramMode} /
+ * {@linkcode PluginWorkspaceApi.closeProgramMode}).
  *
  * - {@linkcode PluginWorkspaceApi.projects} — Create, copy, list, read & rename projects
  * - {@linkcode PluginWorkspaceApi.teams} — Read teams and their members
  * - {@linkcode PluginWorkspaceApi.openPresentMode} / {@linkcode PluginWorkspaceApi.closePresentMode} — Open/close the Present-mode documentation editor
+ * - {@linkcode PluginWorkspaceApi.openProgramMode} / {@linkcode PluginWorkspaceApi.closeProgramMode} — Open/close the Program tab (the spreadsheet the `program.spreadsheet.*` calls run in)
  */
 export abstract class PluginWorkspaceApi {
   /** Projects — create, copy, list, read & rename. See {@linkcode PluginWorkspaceProjectsApi}. */
@@ -68,6 +71,52 @@ export abstract class PluginWorkspaceApi {
    */
   public abstract closePresentMode(): PluginApiReturn<void>
 
+  /**
+   * Open Program mode — the Program tab the `program.spreadsheet.*` calls run in.
+   *
+   * Runs the top bar's own Program-button sequence (remember the preference,
+   * open or re-link the paired Program window) and resolves only once that tab
+   * has connected to the editor over its channel, so a `program.spreadsheet.*`
+   * call issued right after this resolves finds the tab open. The open happens
+   * outside a user gesture, so the browser may block the pop-up; the editor
+   * then shows its "Allow pop-up to continue" modal and this call keeps waiting
+   * (up to ~90s) for the user to confirm. Idempotent — resolves immediately
+   * when the Program tab is already connected, and is a no-op when the plugin is
+   * itself running in the Program tab. Write-gated.
+   *
+   * @throws `PRECONDITION_FAILED` if the user dismisses the pop-up modal or the
+   *   Program tab does not connect within the timeout.
+   *
+   * @examplePrompt Open program mode
+   * @examplePrompt Open the Program tab so I can build a custom sheet
+   * @examplePrompt Switch to the program spreadsheet
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.workspace.openProgramMode()
+   * const { sheets } = await snaptrude.program.spreadsheet.listSheets()
+   * ```
+   */
+  public abstract openProgramMode(): PluginApiReturn<void>
+
+  /**
+   * Close the Program tab.
+   *
+   * Idempotent — a no-op when no Program tab is connected. Write-gated, like
+   * {@linkcode PluginWorkspaceApi.openProgramMode}.
+   *
+   * @throws `PRECONDITION_FAILED` if the tab is still connected after ~15s.
+   *
+   * @examplePrompt Close program mode
+   * @examplePrompt Close the Program tab
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.workspace.closeProgramMode()
+   * ```
+   */
+  public abstract closeProgramMode(): PluginApiReturn<void>
+
   constructor() {}
 }