@snaptrude/plugin-core 0.0.0-dev-20260708130115

package/src/api/program/departments.ts

@@ -0,0 +1,465 @@
+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 area **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>
+
+  /**
+   * 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` | Target area in the response's `units`, or `null` if no target is set |
+ */
+export const PluginProgramDepartment = z.object({
+  id: z.string(),
+  name: z.string(),
+  color: z.string(),
+  targetArea: z.number().nullable(),
+})
+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.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,71 @@
+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"
+
+/**
+ * Program-mode planning APIs.
+ *
+ * The program is the space-planning layer: department groupings with area targets,
+ * 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.adjacency} — Read & compute the department/space adjacency matrix
+ * - {@linkcode PluginProgramApi.layout} — Arrange/pack spaces in the envelope (authored ahead)
+ * - {@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 and read it back
+ * - {@linkcode PluginProgramApi.site} — Read the site/plot planning context
+ * - {@linkcode PluginProgramApi.cores} — Read & trigger vertical-circulation cores
+ * - {@linkcode PluginProgramApi.classification} — Classification catalog + display tags
+ *
+ * Sub-namespaces typed as optional (`?`) are **authored ahead of the host** —
+ * declared so plugins and codegen can see the shape, but not required of host
+ * implementations and kept out of the discovery manifest until the host lands
+ * them (at which point they are promoted to required `abstract` members).
+ *
+ * Accessed via `snaptrude.program`.
+ */
+export abstract class PluginProgramApi {
+  /** Program departments — groupings, area targets, and space assignment. See {@linkcode PluginProgramDepartmentsApi}. */
+  public abstract departments: PluginProgramDepartmentsApi
+  /** Adjacency matrix — read & compute proximity relationships. See {@linkcode PluginProgramAdjacencyApi}. */
+  public abstract adjacency: PluginProgramAdjacencyApi
+  /**
+   * Arrange/pack spaces in the envelope. See {@linkcode PluginProgramLayoutApi}.
+   * _(authored ahead — optional until the host lands it next increment.)_
+   */
+  public 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, export, list, read back. See {@linkcode PluginProgramSpreadsheetApi}. */
+  public abstract spreadsheet: PluginProgramSpreadsheetApi
+  /** Site/plot planning context — total area, parcel footprints, geo rings. See {@linkcode PluginProgramSiteApi}. */
+  public abstract site: PluginProgramSiteApi
+  /** Vertical-circulation cores — read & predicate (live); generation trigger is optional. 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"

package/src/api/program/layout.ts

@@ -0,0 +1,68 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * Program layout — arrange and pack spaces inside the envelope.
+ *
+ * These wrap the product's **Arrange in envelope** / **Pack in envelope**
+ * tools (engine: `Planner.pack_arrange` in the react host) — stages two and
+ * three of the space-planning workflow that starts with
+ * {@linkcode PluginProgramAdjacencyApi} (`program.adjacency`).
+ *
+ * _(Authored ahead — both methods are optional until the host lands them in
+ * the next increment, and are kept out of the discovery manifest until then.)_
+ *
+ * Accessed via `snaptrude.program.layout`.
+ */
+export abstract class PluginProgramLayoutApi {
+  constructor() {}
+
+  /**
+   * Arrange the spaces inside the envelope using the computed adjacency data.
+   * _(Authored ahead — optional until the host lands.)_
+   *
+   * @examplePrompt Arrange the rooms in the envelope
+   * @examplePrompt Lay out the departments inside the building envelope
+   * @examplePrompt Auto-arrange the program spaces
+   *
+   * # Example
+   * ```ts
+   * const { success, error } = await snaptrude.program.layout.arrange()
+   * if (!success) console.log("Arrange failed:", error)
+   * ```
+   */
+  public arrange?: () => PluginApiReturn<PluginProgramLayoutRunResult>
+
+  /**
+   * Pack the spaces into the envelope (a tighter fit than arrange).
+   * _(Authored ahead — optional until the host lands.)_
+   *
+   * @examplePrompt Pack the rooms into the envelope
+   * @examplePrompt Fit the program spaces tightly into the building
+   * @examplePrompt Run pack-in-envelope on this storey
+   *
+   * # Example
+   * ```ts
+   * const { success, error } = await snaptrude.program.layout.pack()
+   * if (!success) console.log("Pack failed:", error)
+   * ```
+   */
+  public pack?: () => PluginApiReturn<PluginProgramLayoutRunResult>
+}
+
+/**
+ * Result of {@linkcode PluginProgramLayoutApi.arrange} /
+ * {@linkcode PluginProgramLayoutApi.pack}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `success` | `boolean` | Whether the layout run completed |
+ * | `error` | `string \| undefined` | Failure reason when `success` is `false` |
+ */
+export const PluginProgramLayoutRunResult = z.object({
+  success: z.boolean(),
+  error: z.string().optional(),
+})
+export type PluginProgramLayoutRunResult = z.infer<
+  typeof PluginProgramLayoutRunResult
+>