@snaptrude/plugin-core 0.0.0-bimsvg-20260928124803

package/src/api/program/departments.ts

@@ -0,0 +1,517 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { PluginAreaUnit } from "./metrics"
+import { ComponentHandle } from "../../handles"
+
+/**
+ * Program departments — read the department groupings of the active program.
+ *
+ * In program mode a **department** is a named, colored grouping of spaces with an
+ * optional gross area **target** and a unit **count** target. This is the program-planning view of departments
+ * (their identity, color, and target area); the underlying space geometry is read
+ * and edited through the geometry namespaces, not here.
+ *
+ * All methods are reads: they return plain records and never throw for a missing
+ * department (`get` returns `null`, `list` returns `[]`).
+ *
+ * Accessed via `snaptrude.program.departments`.
+ */
+export abstract class PluginProgramDepartmentsApi {
+  constructor() {}
+
+  /**
+   * List the departments in the active program.
+   *
+   * Returns every department — well-known (Default, Site, …) and user-created —
+   * with its identity, color, and area target (when one has been set).
+   *
+   * @returns A {@linkcode PluginProgramDepartmentsListResult} with a `departments`
+   *   array (empty when the project has none).
+   *
+   * @examplePrompt List all the departments in my program
+   * @examplePrompt What program groups do I have and what are their target areas?
+   * @examplePrompt Show every department with its colour
+   * @examplePrompt Get the area target for each department
+   * @examplePrompt How many departments are in this project?
+   *
+   * # Example
+   * ```ts
+   * const { units, departments } = await snaptrude.program.departments.list()
+   * for (const d of departments) console.log(d.name, d.color, d.targetArea, units)
+   * ```
+   */
+  public abstract list(): PluginApiReturn<PluginProgramDepartmentsListResult>
+
+  /**
+   * Get a single department by id.
+   *
+   * @param departmentId - The id of the department to read.
+   * @returns The matching {@linkcode PluginProgramDepartment}, or `null` if no
+   *   department has that id.
+   *
+   * @examplePrompt Get the department with id dep_123
+   * @examplePrompt Look up a single department by its id
+   * @examplePrompt What is the target area of this department id?
+   *
+   * # Example
+   * ```ts
+   * const dept = await snaptrude.program.departments.get("dep_123")
+   * if (dept) console.log(dept.name, dept.targetArea)
+   * ```
+   */
+  public abstract get(
+    departmentId: string,
+  ): PluginApiReturn<PluginProgramDepartmentsGetResult>
+
+  /**
+   * Create a new department in the active program.
+   *
+   * Adds a named, colored program grouping. The new department starts empty —
+   * put spaces in it with {@linkcode PluginProgramDepartmentsApi.assign}, and set
+   * its area goal with {@linkcode PluginProgramDepartmentsApi.setTargetArea}.
+   *
+   * @param name - Display name of the new department.
+   * @param color - CSS hex color string (e.g. `"#b5e1dc"`).
+   * @returns The new department's id (read the full record back with
+   *   {@linkcode PluginProgramDepartmentsApi.get}).
+   * @throws If the department could not be created.
+   *
+   * @examplePrompt Create a department called Bedrooms in light blue
+   * @examplePrompt Add a new program group named Circulation with color #cccccc
+   * @examplePrompt Make a Classrooms department
+   * @examplePrompt Set up a Lobby department in the program
+   *
+   * # Example
+   * ```ts
+   * const { departmentId } = await snaptrude.program.departments.create("Bedrooms", "#b5e1dc")
+   * ```
+   */
+  public abstract create(
+    name: string,
+    color: string,
+  ): PluginApiReturn<PluginProgramDepartmentsCreateResult>
+
+  /**
+   * Update a department's name and/or color.
+   *
+   * A **sparse** update: omitted fields are left unchanged. Use
+   * {@linkcode PluginProgramDepartmentsApi.setTargetArea} to change the area
+   * target (not this method).
+   *
+   * @param departmentId - The id of the department to update.
+   * @param options - Any of `name`, `color`; omitted fields are left unchanged.
+   * @returns The updated {@linkcode PluginProgramDepartment} (with the response
+   *   `units` for its `targetArea`).
+   * @throws If no department has the given id.
+   *
+   * @examplePrompt Rename the Bedrooms department to Suites
+   * @examplePrompt Change the Circulation department colour to #ff8800
+   * @examplePrompt Recolour department dep_123
+   * @examplePrompt Update the Lobby department's display name
+   *
+   * # Example
+   * ```ts
+   * const dept = await snaptrude.program.departments.update("dep_123", { name: "Suites" })
+   * ```
+   */
+  public abstract update(
+    departmentId: string,
+    options?: { name?: string; color?: string },
+  ): PluginApiReturn<PluginProgramDepartmentsUpdateResult>
+
+  /**
+   * Assign one or more spaces to a department.
+   *
+   * Moves each space into the given department — an undoable membership change.
+   * A space belongs to exactly one department, so assigning re-homes it from any
+   * previous one. Paired with {@linkcode PluginProgramDepartmentsApi.unassign}.
+   *
+   * @param departmentId - The department to assign the spaces to.
+   * @param spaceIds - The ids of the spaces to move into the department (at
+   *   least one).
+   * @returns The department and the space ids that were assigned.
+   * @throws If the department does not exist or a space id is invalid.
+   *
+   * @examplePrompt Assign the selected rooms to the Bedrooms department
+   * @examplePrompt Put spaces 12 and 13 in the Circulation department
+   * @examplePrompt Move this space into the Lobby department
+   * @examplePrompt Add the kitchen spaces to the Service department
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.program.departments.assign("dep_123", ["sp_1", "sp_2"])
+   * ```
+   */
+  public abstract assign(
+    departmentId: string,
+    spaceIds: ComponentHandle[],
+  ): PluginApiReturn<PluginProgramDepartmentsAssignResult>
+
+  /**
+   * Remove one or more spaces from their department.
+   *
+   * Returns each space to the **Default** department — there is no "no
+   * department" state, so unassigning means reassigning to Default. Paired with
+   * {@linkcode PluginProgramDepartmentsApi.assign}.
+   *
+   * @param spaceIds - The ids of the spaces to remove from their current
+   *   department (at least one).
+   * @returns The space ids that were returned to Default.
+   * @throws If a space id is invalid.
+   *
+   * @examplePrompt Remove the selected rooms from their department
+   * @examplePrompt Unassign space sp_1 from any department
+   * @examplePrompt Clear the department on these spaces
+   * @examplePrompt Take the kitchen out of the Service department
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.program.departments.unassign(["sp_1"])
+   * ```
+   */
+  public abstract unassign(
+    spaceIds: ComponentHandle[],
+  ): PluginApiReturn<PluginProgramDepartmentsUnassignResult>
+
+  /**
+   * Set a department's target area.
+   *
+   * The goal the program metrics compare allocated area against (see
+   * {@linkcode PluginProgramMetricsApi}). Pass `units` to say what unit
+   * `targetArea` is in; it defaults to the project's area units. Read the target
+   * back from {@linkcode PluginProgramDepartmentsApi.get} (`targetArea`).
+   *
+   * @param departmentId - The id of the department whose target to set.
+   * @param targetArea - The target area, in `units`.
+   * @param units - Unit of `targetArea` (defaults to the project's area units).
+   * @returns The updated {@linkcode PluginProgramDepartment} with its `units`.
+   * @throws If no department has the given id.
+   *
+   * @examplePrompt Set the Bedrooms department target area to 2000 sqft
+   * @examplePrompt Give the Circulation department a 500 sqm area target
+   * @examplePrompt Target 1500 square feet for the Classrooms department
+   * @examplePrompt Update the area goal for department dep_123
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.program.departments.setTargetArea("dep_123", 2000, "ft2")
+   * ```
+   */
+  public abstract setTargetArea(
+    departmentId: string,
+    targetArea: number,
+    units?: PluginAreaUnit,
+  ): PluginApiReturn<PluginProgramDepartmentsSetTargetAreaResult>
+
+  /**
+   * Set a department's target unit count.
+   *
+   * The number of units (program blocks) the department is planned for — the
+   * count twin of {@linkcode PluginProgramDepartmentsApi.setTargetArea}, stored
+   * beside the gross area target on the department. Read it back from
+   * {@linkcode PluginProgramDepartmentsApi.get} (`targetCount`).
+   *
+   * @param departmentId - The id of the department whose count to set.
+   * @param targetCount - The target number of units (a non-negative integer).
+   * @returns The updated {@linkcode PluginProgramDepartment} with its `units`.
+   * @throws If no department has the given id.
+   *
+   * @examplePrompt Set the Bedrooms department unit count to 12
+   * @examplePrompt The program needs 4 clinic blocks — update the department count
+   * @examplePrompt Update the target count for department dep_123
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.program.departments.setTargetCount("dep_123", 12)
+   * ```
+   */
+  public abstract setTargetCount(
+    departmentId: string,
+    targetCount: number,
+  ): PluginApiReturn<PluginProgramDepartmentsSetTargetCountResult>
+
+  /**
+   * Delete a department.
+   *
+   * Any spaces still assigned to it are returned to the **Default** department
+   * (no space is left orphaned). The reserved departments (Default, Site,
+   * Envelope, Core) cannot be deleted.
+   *
+   * @param departmentId - The id of the department to delete.
+   * @returns The id of the deleted department and the spaces that were reassigned
+   *   to Default.
+   * @throws If no department has the given id, or it is a reserved department.
+   *
+   * @examplePrompt Delete the Bedrooms department
+   * @examplePrompt Remove the empty Circulation department
+   * @examplePrompt Delete department dep_123 and move its rooms to Default
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.program.departments.delete("dep_123")
+   * ```
+   */
+  public delete?: (
+    departmentId: string,
+  ) => PluginApiReturn<PluginProgramDepartmentsDeleteResult>
+}
+
+/**
+ * A department in the active program. Its `targetArea` is in the enclosing
+ * response's `units` (see the area-units convention in
+ * {@linkcode PluginAreaUnit}).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Unique department id |
+ * | `name` | `string` | Display name |
+ * | `color` | `string` | CSS hex color string (e.g. `"#b5e1dc"`) |
+ * | `targetArea` | `number \| null` | Gross target area in the response's `units`, or `null` if no target is set |
+ * | `targetCount` | `number` | Target number of units / program blocks (`0` when unset) |
+ */
+export const PluginProgramDepartment = z.object({
+  id: z.string(),
+  name: z.string(),
+  color: z.string(),
+  targetArea: z.number().nullable(),
+  targetCount: z.number(),
+})
+export type PluginProgramDepartment = z.infer<typeof PluginProgramDepartment>
+
+/**
+ * Result of {@linkcode PluginProgramDepartmentsApi.list}. Per the area-units
+ * convention, `units` sits on this response envelope (not on each record).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `units` | `"ft2" \| "m2"` | The unit every `targetArea` below is reported in |
+ * | `departments` | {@linkcode PluginProgramDepartment}`[]` | All departments in the active program |
+ */
+export const PluginProgramDepartmentsListResult = z.object({
+  units: PluginAreaUnit,
+  departments: z.array(PluginProgramDepartment),
+})
+export type PluginProgramDepartmentsListResult = z.infer<
+  typeof PluginProgramDepartmentsListResult
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramDepartmentsApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `departmentId` | `string` | The id of the department to read |
+ */
+export const PluginProgramDepartmentsGetArgs = z.object({
+  departmentId: z.string(),
+})
+export type PluginProgramDepartmentsGetArgs = z.infer<
+  typeof PluginProgramDepartmentsGetArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramDepartmentsApi.get} — the department, or
+ * `null` when no department has the given id. This is a bare `.get` record, so
+ * per the area-units convention `units` is carried on the record itself.
+ */
+export const PluginProgramDepartmentsGetResult = PluginProgramDepartment.extend(
+  {
+    units: PluginAreaUnit,
+  },
+).nullable()
+export type PluginProgramDepartmentsGetResult = z.infer<
+  typeof PluginProgramDepartmentsGetResult
+>
+
+/**
+ * A department record with its area `units` — the shape returned by the
+ * single-record department writes (`update`, `setTargetArea`). Per the
+ * area-units convention, a bare record carries `units` on itself.
+ */
+export const PluginProgramDepartmentRecord = PluginProgramDepartment.extend({
+  units: PluginAreaUnit,
+})
+export type PluginProgramDepartmentRecord = z.infer<
+  typeof PluginProgramDepartmentRecord
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramDepartmentsApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | Display name of the new department |
+ * | `color` | `string` | CSS hex color string (e.g. `"#b5e1dc"`) |
+ */
+export const PluginProgramDepartmentsCreateArgs = z.object({
+  name: z.string(),
+  color: z.string(),
+})
+export type PluginProgramDepartmentsCreateArgs = z.infer<
+  typeof PluginProgramDepartmentsCreateArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramDepartmentsApi.create} — the id of the
+ * newly created department.
+ */
+export const PluginProgramDepartmentsCreateResult = z.object({
+  departmentId: z.string(),
+})
+export type PluginProgramDepartmentsCreateResult = z.infer<
+  typeof PluginProgramDepartmentsCreateResult
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramDepartmentsApi.update}. Sparse — only
+ * the provided fields are changed.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `departmentId` | `string` | The id of the department to update |
+ * | `name` | `string \| undefined` | New display name (unchanged if omitted) |
+ * | `color` | `string \| undefined` | New CSS hex color (unchanged if omitted) |
+ */
+export const PluginProgramDepartmentsUpdateArgs = z.object({
+  departmentId: z.string(),
+  name: z.string().optional(),
+  color: z.string().optional(),
+})
+export type PluginProgramDepartmentsUpdateArgs = z.infer<
+  typeof PluginProgramDepartmentsUpdateArgs
+>
+
+/** Result of {@linkcode PluginProgramDepartmentsApi.update} — the updated record. */
+export const PluginProgramDepartmentsUpdateResult =
+  PluginProgramDepartmentRecord
+export type PluginProgramDepartmentsUpdateResult = z.infer<
+  typeof PluginProgramDepartmentsUpdateResult
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramDepartmentsApi.assign}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `departmentId` | `string` | The department to assign the spaces to |
+ * | `spaceIds` | `ComponentHandle[]` | The ids of the spaces to move into the department |
+ */
+export const PluginProgramDepartmentsAssignArgs = z.object({
+  departmentId: z.string(),
+  spaceIds: z.array(ComponentHandle).min(1),
+})
+export type PluginProgramDepartmentsAssignArgs = z.infer<
+  typeof PluginProgramDepartmentsAssignArgs
+>
+
+/** Result of {@linkcode PluginProgramDepartmentsApi.assign}. */
+export const PluginProgramDepartmentsAssignResult = z.object({
+  departmentId: z.string(),
+  spaceIds: z.array(ComponentHandle),
+})
+export type PluginProgramDepartmentsAssignResult = z.infer<
+  typeof PluginProgramDepartmentsAssignResult
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramDepartmentsApi.unassign}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spaceIds` | `ComponentHandle[]` | The ids of the spaces to return to the Default department |
+ */
+export const PluginProgramDepartmentsUnassignArgs = z.object({
+  spaceIds: z.array(ComponentHandle).min(1),
+})
+export type PluginProgramDepartmentsUnassignArgs = z.infer<
+  typeof PluginProgramDepartmentsUnassignArgs
+>
+
+/** Result of {@linkcode PluginProgramDepartmentsApi.unassign}. */
+export const PluginProgramDepartmentsUnassignResult = z.object({
+  spaceIds: z.array(ComponentHandle),
+})
+export type PluginProgramDepartmentsUnassignResult = z.infer<
+  typeof PluginProgramDepartmentsUnassignResult
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramDepartmentsApi.setTargetArea}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `departmentId` | `string` | The id of the department whose target to set |
+ * | `targetArea` | `number` | The target area, in `units` |
+ * | `units` | `"ft2" \| "m2" \| undefined` | Unit of `targetArea` (defaults to the project's area units) |
+ */
+export const PluginProgramDepartmentsSetTargetAreaArgs = z.object({
+  departmentId: z.string(),
+  targetArea: z.number(),
+  units: PluginAreaUnit.optional(),
+})
+export type PluginProgramDepartmentsSetTargetAreaArgs = z.infer<
+  typeof PluginProgramDepartmentsSetTargetAreaArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramDepartmentsApi.setTargetArea} — the updated
+ * department record with its `units`.
+ */
+export const PluginProgramDepartmentsSetTargetAreaResult =
+  PluginProgramDepartmentRecord
+export type PluginProgramDepartmentsSetTargetAreaResult = z.infer<
+  typeof PluginProgramDepartmentsSetTargetAreaResult
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramDepartmentsApi.setTargetCount}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `departmentId` | `string` | The id of the department whose count to set |
+ * | `targetCount` | `number` | Target number of units (non-negative integer) |
+ */
+export const PluginProgramDepartmentsSetTargetCountArgs = z.object({
+  departmentId: z.string(),
+  targetCount: z.number().int().nonnegative(),
+})
+export type PluginProgramDepartmentsSetTargetCountArgs = z.infer<
+  typeof PluginProgramDepartmentsSetTargetCountArgs
+>
+
+/** Result of {@linkcode PluginProgramDepartmentsApi.setTargetCount} — the updated record with `units`. */
+export const PluginProgramDepartmentsSetTargetCountResult =
+  PluginProgramDepartmentRecord
+export type PluginProgramDepartmentsSetTargetCountResult = z.infer<
+  typeof PluginProgramDepartmentsSetTargetCountResult
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramDepartmentsApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `departmentId` | `string` | The id of the department to delete |
+ */
+export const PluginProgramDepartmentsDeleteArgs = z.object({
+  departmentId: z.string(),
+})
+export type PluginProgramDepartmentsDeleteArgs = z.infer<
+  typeof PluginProgramDepartmentsDeleteArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramDepartmentsApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `departmentId` | `string` | The id of the deleted department |
+ * | `reassignedSpaceIds` | `ComponentHandle[]` | Spaces that were returned to the Default department |
+ */
+export const PluginProgramDepartmentsDeleteResult = z.object({
+  departmentId: z.string(),
+  reassignedSpaceIds: z.array(ComponentHandle),
+})
+export type PluginProgramDepartmentsDeleteResult = z.infer<
+  typeof PluginProgramDepartmentsDeleteResult
+>

package/src/api/program/index.ts

@@ -0,0 +1,73 @@
+import { PluginProgramDepartmentsApi } from "./departments"
+import { PluginProgramAdjacencyApi } from "./adjacency"
+import { PluginProgramLayoutApi } from "./layout"
+import { PluginProgramMetricsApi } from "./metrics"
+import { PluginProgramSpreadsheetApi } from "./spreadsheet"
+import { PluginProgramSiteApi } from "./site"
+import { PluginProgramCoresApi } from "./cores"
+import { PluginProgramClassificationApi } from "./classification"
+import { PluginProgramAreasApi } from "./areas"
+import { PluginProgramMetadataApi } from "./metadata"
+import { PluginProgramLabelsApi } from "./labels"
+
+/**
+ * Program-mode planning APIs.
+ *
+ * The program is the space-planning layer: department groupings with area targets,
+ * the labels (program rows) inside them, the metrics that track allocated area
+ * against those targets, and the reports that render program/takeoff data to
+ * spreadsheet sheets. Reads describe the *plan* (intent + targets); the geometry
+ * that realizes the plan is authored through the geometry namespaces.
+ *
+ * - {@linkcode PluginProgramApi.departments} — Read & edit program departments (groupings + targets)
+ * - {@linkcode PluginProgramApi.labels} — Read & edit program labels (program rows: per-type area/count targets)
+ * - {@linkcode PluginProgramApi.metadata} — Read & edit program metadata (custom columns) on spaces
+ * - {@linkcode PluginProgramApi.adjacency} — Read & compute the department/space adjacency matrix
+ * - {@linkcode PluginProgramApi.layout} — Arrange/pack spaces in the envelope
+ * - {@linkcode PluginProgramApi.metrics} — Read the area-program summary
+ * - {@linkcode PluginProgramApi.areas} — FAR / built-up-area rollup and groupings
+ * - {@linkcode PluginProgramApi.spreadsheet} — Render program data to sheets, custom grouped sheets, read back
+ * - {@linkcode PluginProgramApi.site} — Read site/plot context and read/update Site Analysis
+ * - {@linkcode PluginProgramApi.cores} — Read & predicate vertical-circulation cores (reads only)
+ * - {@linkcode PluginProgramApi.classification} — Classification catalog + display tags
+ *
+ * Accessed via `snaptrude.program`.
+ */
+export abstract class PluginProgramApi {
+  /** Program departments — groupings, area targets, and space assignment. See {@linkcode PluginProgramDepartmentsApi}. */
+  public abstract departments: PluginProgramDepartmentsApi
+  /** Program labels — the program rows with per-type area/count targets. See {@linkcode PluginProgramLabelsApi}. */
+  public abstract labels: PluginProgramLabelsApi
+  /** Program metadata — custom columns and their per-space values. See {@linkcode PluginProgramMetadataApi}. */
+  public abstract metadata: PluginProgramMetadataApi
+  /** Adjacency matrix — read & compute proximity relationships. See {@linkcode PluginProgramAdjacencyApi}. */
+  public abstract adjacency: PluginProgramAdjacencyApi
+  /** Arrange/pack spaces in the envelope (async job family). See {@linkcode PluginProgramLayoutApi}. */
+  public abstract layout: PluginProgramLayoutApi
+  /** Area-program summary — targets vs allocated area. See {@linkcode PluginProgramMetricsApi}. */
+  public abstract metrics: PluginProgramMetricsApi
+  /** FAR / built-up-area rollup and groupings. See {@linkcode PluginProgramAreasApi}. */
+  public abstract areas: PluginProgramAreasApi
+  /** Spreadsheet reports — render tables to sheets, custom grouped sheets, export, read back. See {@linkcode PluginProgramSpreadsheetApi}. */
+  public abstract spreadsheet: PluginProgramSpreadsheetApi
+  /** Site/plot context and persisted Site Analysis. See {@linkcode PluginProgramSiteApi}. */
+  public abstract site: PluginProgramSiteApi
+  /** Vertical-circulation cores — read & predicate (reads only). See {@linkcode PluginProgramCoresApi}. */
+  public abstract cores: PluginProgramCoresApi
+  /** Classification catalog (space/area/mass types) + display tags. See {@linkcode PluginProgramClassificationApi}. */
+  public abstract classification: PluginProgramClassificationApi
+
+  constructor() {}
+}
+
+export * from "./departments"
+export * from "./adjacency"
+export * from "./layout"
+export * from "./metrics"
+export * from "./spreadsheet"
+export * from "./site"
+export * from "./cores"
+export * from "./classification"
+export * from "./areas"
+export * from "./metadata"
+export * from "./labels"