@snaptrude/plugin-core 0.3.0 → 0.6.0

package/src/api/program/cores.ts

@@ -0,0 +1,171 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * Program cores — the building's vertical-circulation cores (lift / stair / shaft
+ * shells).
+ *
+ * Read the cores in the scene, test whether a space is a core, and trigger core
+ * generation from a layout. `create` is a **thin trigger**: the program hands a
+ * core layout to the core-generation engine, which authors the geometry — the
+ * core geometry itself is owned by the geometry layer, not here (the exact
+ * layout ↔ engine payload is coordinated with the geometry owner).
+ *
+ * `list`/`isCore` are reads; `create` triggers generation.
+ *
+ * Accessed via `snaptrude.program.cores`.
+ */
+export abstract class PluginProgramCoresApi {
+  constructor() {}
+
+  /**
+   * List the cores currently in the building.
+   *
+   * @returns A {@linkcode PluginProgramCoresListResult} with each core's id,
+   *   core group, and storey (empty when there are none).
+   *
+   * @examplePrompt List the cores in the building
+   * @examplePrompt How many cores are placed?
+   * @examplePrompt Show me the lift and stair cores
+   * @examplePrompt Which storeys have cores?
+   *
+   * # Example
+   * ```ts
+   * const { cores } = await snaptrude.program.cores.list()
+   * ```
+   */
+  public abstract list(): PluginApiReturn<PluginProgramCoresListResult>
+
+  /**
+   * Test whether a space is a circulation core element.
+   *
+   * @param id - The id of the space to test.
+   * @returns `true` if the space is a core element.
+   *
+   * @examplePrompt Is this space a core?
+   * @examplePrompt Does this mass belong to the core?
+   * @examplePrompt Check if space sp_1 is a circulation core
+   *
+   * # Example
+   * ```ts
+   * const isCore = await snaptrude.program.cores.isCore("sp_1")
+   * ```
+   */
+  public abstract isCore(id: string): PluginApiReturn<boolean>
+
+  /**
+   * Generate core geometry from a layout (thin trigger).
+   *
+   * Hands the core layout to the core-generation engine and returns how many core
+   * elements were created. The geometry is authored by the engine, not here.
+   * _(Authored ahead — optional until the host's geometry adapter lands; the
+   * reads {@linkcode PluginProgramCoresApi.list}/{@linkcode PluginProgramCoresApi.isCore}
+   * are live.)_
+   *
+   * @param cores - The {@linkcode PluginProgramCoreSpec} layout of cores to
+   *   generate.
+   * @param lengthUnit - Unit of the spec dimensions (default project unit).
+   * @returns A {@linkcode PluginProgramCoresCreateResult} with the created count.
+   * @throws If the layout could not be realized.
+   *
+   * @examplePrompt Generate the building cores from this layout
+   * @examplePrompt Place the elevator and stair cores
+   * @examplePrompt Create the service core shells
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.program.cores.create([
+   *   { type: "lift", position: { x: 0, y: 0, z: 0 }, width: 3, depth: 4 },
+   * ])
+   * ```
+   */
+  public create?: (
+    cores: PluginProgramCoreSpec[],
+    lengthUnit?: "mm" | "m" | "ft",
+  ) => PluginApiReturn<PluginProgramCoresCreateResult>
+}
+
+/**
+ * A circulation core element in the building.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Component id of the core element |
+ * | `groupId` | `string` | Id of the core group this element belongs to |
+ * | `storey` | `number` | Storey (floor number) the element sits on |
+ */
+export const PluginProgramCore = z.object({
+  id: z.string(),
+  groupId: z.string(),
+  storey: z.number(),
+})
+export type PluginProgramCore = z.infer<typeof PluginProgramCore>
+
+/** Result of {@linkcode PluginProgramCoresApi.list}. */
+export const PluginProgramCoresListResult = z.object({
+  cores: z.array(PluginProgramCore),
+})
+export type PluginProgramCoresListResult = z.infer<
+  typeof PluginProgramCoresListResult
+>
+
+/** Arguments for {@linkcode PluginProgramCoresApi.isCore}. */
+export const PluginProgramCoresIsCoreArgs = z.object({
+  id: z.string(),
+})
+export type PluginProgramCoresIsCoreArgs = z.infer<
+  typeof PluginProgramCoresIsCoreArgs
+>
+
+/**
+ * One core to generate. The geometry layer interprets this layout (the exact
+ * fields are coordinated with the geometry owner).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `type` | `string \| undefined` | Core kind (e.g. `"lift"`, `"stair"`, `"shaft"`) |
+ * | `position` | `{ x; y; z }` | Base position of the core |
+ * | `width` | `number` | Core width, in `lengthUnit` |
+ * | `depth` | `number` | Core depth, in `lengthUnit` |
+ * | `fromStorey` | `number \| undefined` | First storey the core spans |
+ * | `toStorey` | `number \| undefined` | Last storey the core spans |
+ */
+export const PluginProgramCoreSpec = z.object({
+  type: z.string().optional(),
+  position: z.object({ x: z.number(), y: z.number(), z: z.number() }),
+  width: z.number(),
+  depth: z.number(),
+  fromStorey: z.number().optional(),
+  toStorey: z.number().optional(),
+})
+export type PluginProgramCoreSpec = z.infer<typeof PluginProgramCoreSpec>
+
+/**
+ * Arguments for {@linkcode PluginProgramCoresApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `cores` | {@linkcode PluginProgramCoreSpec}`[]` | The cores to generate |
+ * | `lengthUnit` | `"mm" \| "m" \| "ft" \| undefined` | Unit of the spec dimensions (default project unit) |
+ */
+export const PluginProgramCoresCreateArgs = z.object({
+  cores: z.array(PluginProgramCoreSpec),
+  lengthUnit: z.enum(["mm", "m", "ft"]).optional(),
+})
+export type PluginProgramCoresCreateArgs = z.infer<
+  typeof PluginProgramCoresCreateArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramCoresApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `createdCount` | `number` | Number of core elements created |
+ */
+export const PluginProgramCoresCreateResult = z.object({
+  createdCount: z.number(),
+})
+export type PluginProgramCoresCreateResult = z.infer<
+  typeof PluginProgramCoresCreateResult
+>

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