@snaptrude/plugin-core 0.0.5 → 0.0.7

package/src/api/entity/space.ts

@@ -4,32 +4,209 @@ import { PVec3 } from "../core/math/vec3"
 import { PQuat } from "../core/math/quat"
 import { PProfile } from "../core/geom/profile"
 
+/**
+ * Space (room/mass) management — create, query, and delete spaces.
+ *
+ * A **space** is a 3D volume representing a room or mass in the
+ * Snaptrude scene. Spaces live on a particular story and carry
+ * properties such as name, area, department, and room type.
+ *
+ * All methods are **host API calls** that return Promises and support
+ * undo/redo via Snaptrude's command system.
+ *
+ * Accessed via `snaptrude.entity.space`.
+ */
 export abstract class PluginSpaceApi {
   constructor() {}
 
+  /**
+   * Create a rectangular (box) space.
+   *
+   * Generates an axis-aligned box with the given dimensions at the
+   * specified position. The created space is automatically assigned
+   * to the active story and a default department.
+   *
+   * @param args - An object containing:
+   *   - {@linkcode PluginSpaceCreateRectangularArgs.position args.position} — Origin
+   *     position as a {@linkcode PVec3} in Babylon units
+   *   - {@linkcode PluginSpaceCreateRectangularArgs.dimensions args.dimensions} — Box
+   *     dimensions `{ width, height, depth }` in Babylon units
+   * @returns A {@linkcode PluginSpaceCreateRectangularResult} with the `spaceId`
+   *   of the created space
+   * @throws If space creation fails
+   *
+   * # Example
+   * ```ts
+   * const { vec3 } = snaptrude.core.math
+   *
+   * const { spaceId } = await snaptrude.entity.space.createRectangular({
+   *   position: vec3.new(0, 0, 0),
+   *   dimensions: { width: 5, height: 3, depth: 4 },
+   * })
+   * ```
+   */
   public abstract createRectangular({
     position,
     dimensions,
   }: PluginSpaceCreateRectangularArgs): PluginApiReturn<PluginSpaceCreateRectangularResult>
 
+  /**
+   * Create a space by extruding a 2D profile.
+   *
+   * The {@linkcode PluginSpaceCreateFromProfileArgs.profile profile} is extruded
+   * upward (along the Y axis) by {@linkcode PluginSpaceCreateFromProfileArgs.extrudeHeight
+   * extrudeHeight}, then offset by {@linkcode PluginSpaceCreateFromProfileArgs.position
+   * position}. The created space is automatically assigned to the active story
+   * and a default department.
+   *
+   * Use {@linkcode PluginProfileApi.fromLinePoints} to quickly build a profile
+   * from a list of points.
+   *
+   * @param args - An object containing:
+   *   - {@linkcode PluginSpaceCreateFromProfileArgs.profile args.profile} — A closed
+   *     {@linkcode PProfile} defining the floor shape
+   *   - {@linkcode PluginSpaceCreateFromProfileArgs.extrudeHeight args.extrudeHeight} —
+   *     Extrusion height in Babylon units
+   *   - {@linkcode PluginSpaceCreateFromProfileArgs.position args.position} — Offset
+   *     position as a {@linkcode PVec3} in Babylon units
+   * @returns A {@linkcode PluginSpaceCreateFromProfileResult} with the `spaceId`
+   *   of the created space
+   * @throws If the profile is invalid or mesh creation fails
+   *
+   * # Example
+   * ```ts
+   * const { vec3 } = snaptrude.core.math
+   *
+   * const profile = await snaptrude.core.geom.profile.fromLinePoints({
+   *   points: [
+   *     vec3.new(0, 0, 0),
+   *     vec3.new(10, 0, 0),
+   *     vec3.new(10, 0, 8),
+   *     vec3.new(0, 0, 8),
+   *   ],
+   * })
+   *
+   * const { spaceId } = await snaptrude.entity.space.createFromProfile({
+   *   profile,
+   *   extrudeHeight: 3,
+   *   position: vec3.new(0, 0, 0),
+   * })
+   * ```
+   */
   public abstract createFromProfile({
     profile,
     extrudeHeight,
     position,
   }: PluginSpaceCreateFromProfileArgs): PluginApiReturn<PluginSpaceCreateFromProfileResult>
 
+  /**
+   * Get the IDs of all spaces in the current project.
+   *
+   * Returns every space (mass that is not a building) across all stories.
+   * Use the returned IDs with {@linkcode PluginSpaceApi.get} to query
+   * individual space properties.
+   *
+   * @returns A {@linkcode PluginSpaceGetAllResult} with a `spacesIds` array
+   *
+   * # Example
+   * ```ts
+   * const { spacesIds } = await snaptrude.entity.space.getAll()
+   * console.log(`Project has ${spacesIds.length} spaces`)
+   * ```
+   */
   public abstract getAll(): PluginApiReturn<PluginSpaceGetAllResult>
 
+  /**
+   * Get properties of a space by its ID.
+   *
+   * Only the properties listed in {@linkcode PluginSpaceGetArgs.properties
+   * args.properties} are returned — unlisted properties will be `undefined`
+   * in the result.
+   *
+   * @param args - An object containing:
+   *   - {@linkcode PluginSpaceGetArgs.spaceId args.spaceId} — The unique space ID
+   *     (as returned by creation methods or {@linkcode PluginSpaceApi.getAll})
+   *   - {@linkcode PluginSpaceGetArgs.properties args.properties} — Array of property
+   *     names to retrieve. See {@linkcode PluginSpaceGetProperty} for available values.
+   * @returns A partial {@linkcode PluginSpaceGetResult} containing only the requested
+   *   properties
+   * @throws If the space does not exist or the component is not a space/mass
+   *
+   * # Example
+   * ```ts
+   * const info = await snaptrude.entity.space.get({
+   *   spaceId: "some-space-id",
+   *   properties: ["name", "area", "position"],
+   * })
+   * console.log(info.name, info.area, info.position)
+   * ```
+   */
   public abstract get({
     spaceId,
     properties,
   }: PluginSpaceGetArgs): PluginApiReturn<PluginSpaceGetResult>
 
-  public abstract deleteById({
+  /**
+   * Delete a space by its ID.
+   *
+   * Permanently removes the space and its associated mesh from the scene.
+   * This operation is undoable via Snaptrude's command system.
+   *
+   * @param args - An object containing:
+   *   - {@linkcode PluginSpaceDeleteArgs.spaceId args.spaceId} — The unique space ID
+   *     to delete
+   * @throws If the space does not exist or the component is not a space/mass
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.entity.space.delete({ spaceId: "some-space-id" })
+   * ```
+   */
+  public abstract delete({
     spaceId,
-  }: PluginSpaceDeleteByIdArgs): PluginApiReturn<PluginSpaceDeleteByIdResult>
+  }: PluginSpaceDeleteArgs): PluginApiReturn<PluginSpaceDeleteResult>
+
+  /**
+   * Update properties of a space by its ID.
+   *
+   * Only the properties provided in {@linkcode PluginSpaceUpdateArgs.properties
+   * args.properties} will be updated — omitted properties remain unchanged.
+   * This operation is undoable via Snaptrude's command system.
+   *
+   * @param args - An object containing:
+   *   - {@linkcode PluginSpaceUpdateArgs.spaceId args.spaceId} — The unique space ID
+   *     to update
+   *   - {@linkcode PluginSpaceUpdateArgs.properties args.properties} — Key/value pairs
+   *     of properties to update. See {@linkcode PluginSpaceUpdateArgs} for supported fields.
+   * @returns A {@linkcode PluginSpaceUpdateResult} echoing back the `spaceId` and
+   *   the updated property values
+   * @throws If the space does not exist or the component is not a space/mass
+   *
+   * # Example
+   * ```ts
+   * const result = await snaptrude.entity.space.update({
+   *   spaceId: "some-space-id",
+   *   properties: {
+   *     room_type: "Kitchen",
+   *     massType: "Room",
+   *     departmentId: "CORE",
+   *   },
+   * })
+   * ```
+   */
+  public abstract update(
+    args: PluginSpaceUpdateArgs
+  ): PluginApiReturn<PluginSpaceUpdateResult>
 }
 
+/**
+ * Arguments for {@linkcode PluginSpaceApi.createRectangular}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `position` | {@linkcode PVec3} | Origin position in Babylon units |
+ * | `dimensions` | `{ width, height, depth }` | Box dimensions in Babylon units |
+ */
 export const PluginSpaceCreateRectangularArgs = z.object({
   position: PVec3,
   dimensions: z.object({
@@ -39,41 +216,131 @@ export const PluginSpaceCreateRectangularArgs = z.object({
   }),
 })
 
-export type PluginSpaceCreateRectangularArgs = z.infer<typeof PluginSpaceCreateRectangularArgs>
+export type PluginSpaceCreateRectangularArgs = z.infer<
+  typeof PluginSpaceCreateRectangularArgs
+>
 
+/**
+ * Result of {@linkcode PluginSpaceApi.createRectangular}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spaceId` | `string` | Unique ID of the created space |
+ */
 export const PluginSpaceCreateRectangularResult = z.object({
   spaceId: z.string(),
 })
 
-export type PluginSpaceCreateRectangularResult = z.infer<typeof PluginSpaceCreateRectangularResult>
+export type PluginSpaceCreateRectangularResult = z.infer<
+  typeof PluginSpaceCreateRectangularResult
+>
 
+/**
+ * Arguments for {@linkcode PluginSpaceApi.createFromProfile}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `profile` | {@linkcode PProfile} | Closed 2D profile defining the floor shape |
+ * | `extrudeHeight` | `number` | Extrusion height in Babylon units |
+ * | `position` | {@linkcode PVec3} | Offset position in Babylon units |
+ */
 export const PluginSpaceCreateFromProfileArgs = z.object({
   profile: PProfile,
   extrudeHeight: z.number(),
   position: PVec3,
 })
 
-export type PluginSpaceCreateFromProfileArgs = z.infer<typeof PluginSpaceCreateFromProfileArgs>
+export type PluginSpaceCreateFromProfileArgs = z.infer<
+  typeof PluginSpaceCreateFromProfileArgs
+>
 
+/**
+ * Result of {@linkcode PluginSpaceApi.createFromProfile}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spaceId` | `string` | Unique ID of the created space |
+ */
 export const PluginSpaceCreateFromProfileResult = z.object({
   spaceId: z.string(),
 })
 
-export type PluginSpaceCreateFromProfileResult = z.infer<typeof PluginSpaceCreateFromProfileResult>
+export type PluginSpaceCreateFromProfileResult = z.infer<
+  typeof PluginSpaceCreateFromProfileResult
+>
 
+/**
+ * Available properties that can be queried on a space.
+ *
+ * **Basic:**
+ * | Value | Return Type | Description |
+ * |---|---|---|
+ * | `"id"` | `string` | Unique space identifier |
+ * | `"type"` | `string` | Component type |
+ * | `"room_type"` | `string` | Room type classification |
+ * | `"name"` | `string` | Display name of the space |
+ *
+ * **Derived from parametric data:**
+ * | Value | Return Type | Description |
+ * |---|---|---|
+ * | `"area"` | `number` | Bottom face area (from `areas_bottomFace`) |
+ * | `"breadth"` | `number` | Breadth dimension |
+ * | `"depth"` | `number` | Depth dimension |
+ * | `"height"` | `number` | Height dimension |
+ * | `"massType"` | `string \| null` | Mass type classification |
+ * | `"spaceType"` | `string \| null` | Space type classification (Room, Balcony, etc.) |
+ * | `"storey"` | `number \| null` | Story the space belongs to |
+ * | `"departmentId"` | `string \| null` | Assigned department ID |
+ * | `"departmentName"` | `string` | Assigned department name |
+ * | `"departmentColor"` | `string` | Assigned department color (hex/CSS) |
+ *
+ * **Derived from mesh:**
+ * | Value | Return Type | Description |
+ * |---|---|---|
+ * | `"position"` | {@linkcode PVec3} | Local position relative to parent |
+ * | `"absolutePosition"` | {@linkcode PVec3} | Absolute position in the scene |
+ * | `"rotation"` | {@linkcode PVec3} | Euler rotation angles (radians) |
+ * | `"rotationQuaternion"` | {@linkcode PQuat} \| `null` | Quaternion rotation, or `null` if unset |
+ *
+ * **Derived from brep:**
+ * | Value | Return Type | Description |
+ * |---|---|---|
+ * | `"planPoints"` | {@linkcode PVec3}`[]` | Bottom outer profile points in world space with `y = 0` (2D plan). No closing duplicate point. |
+ */
 export const PluginSpaceGetProperty = z.enum([
+  // Basic
   "id",
   "type",
   "room_type",
   "name",
+  // Derived from parametric data
   "area",
-  "department",
+  "breadth",
+  "depth",
+  "height",
+  "massType",
+  "spaceType",
+  "storey",
+  "departmentId",
+  "departmentName",
+  "departmentColor",
+  // Derived from mesh
   "position",
   "absolutePosition",
   "rotation",
   "rotationQuaternion",
+  // Derived from brep
+  "planPoints",
 ])
 
+/**
+ * Arguments for {@linkcode PluginSpaceApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spaceId` | `string` | The space ID to query |
+ * | `properties` | {@linkcode PluginSpaceGetProperty}`[]` | Properties to retrieve |
+ */
 export const PluginSpaceGetArgs = z.object({
   spaceId: z.string(),
   properties: z.array(PluginSpaceGetProperty),
@@ -81,33 +348,202 @@ export const PluginSpaceGetArgs = z.object({
 
 export type PluginSpaceGetArgs = z.infer<typeof PluginSpaceGetArgs>
 
+/**
+ * Supported space type values.
+ *
+ * Mirrors the internal `SpaceType` enum from `spaceType.types.ts`.
+ *
+ * | Value | Description |
+ * |---|---|
+ * | `"Room"` | Standard room |
+ * | `"Program Block"` | Program/department block |
+ * | `"Balcony"` | Balcony space |
+ * | `"Road"` | Road |
+ * | `"Garden"` | Garden area |
+ * | `"Deck"` | Deck |
+ * | `"Pool"` | Pool |
+ * | `"Walkway"` | Walkway |
+ */
+export const PluginSpaceType = z.enum([
+  "Room",
+  "Program Block",
+  "Balcony",
+  "Road",
+  "Garden",
+  "Deck",
+  "Pool",
+  "Walkway",
+])
+
+/**
+ * Result of {@linkcode PluginSpaceApi.get}.
+ *
+ * A partial object — only the properties that were requested in
+ * {@linkcode PluginSpaceGetArgs.properties} will be present.
+ */
 export const PluginSpaceGetResult = z
   .object({
+    // Basic
     id: z.string(),
     type: z.string(),
     room_type: z.string(),
     name: z.string(),
+    // Derived from parametric data
     area: z.number(),
-    department: z.string(),
+    breadth: z.number(),
+    depth: z.number(),
+    height: z.number(),
+    massType: z.string().nullable(),
+    spaceType: PluginSpaceType.nullable(),
+    storey: z.number().nullable(),
+    departmentId: z.string().nullable(),
+    departmentName: z.string(),
+    departmentColor: z.string(),
+    // Derived from mesh
     position: PVec3,
     absolutePosition: PVec3,
     rotation: PVec3,
     rotationQuaternion: PQuat.nullable(),
+    // Derived from brep
+    planPoints: z.array(PVec3),
   })
   .partial()
 
 export type PluginSpaceGetResult = z.infer<typeof PluginSpaceGetResult>
 
+/**
+ * Result of {@linkcode PluginSpaceApi.getAll}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spacesIds` | `string[]` | IDs of all spaces in the project |
+ */
 export const PluginSpaceGetAllResult = z.object({
   spacesIds: z.array(z.string()),
 })
 
 export type PluginSpaceGetAllResult = z.infer<typeof PluginSpaceGetAllResult>
 
-export const PluginSpaceDeleteByIdArgs = z.object({
+/**
+ * Arguments for {@linkcode PluginSpaceApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spaceId` | `string` | The space ID to delete |
+ */
+export const PluginSpaceDeleteArgs = z.object({
+  spaceId: z.string(),
+})
+
+export type PluginSpaceDeleteArgs = z.infer<typeof PluginSpaceDeleteArgs>
+
+/** Result type for {@linkcode PluginSpaceApi.delete} — returns nothing on success. */
+export type PluginSpaceDeleteResult = void
+
+/**
+ * Supported mass type values for {@linkcode PluginSpaceUpdateArgs.properties.massType}.
+ *
+ * Mirrors the internal `MASS_TYPES` enum.
+ *
+ * | Value | Description |
+ * |---|---|
+ * | `"Plinth"` | Plinth mass |
+ * | `"Void"` | Void/cut-out |
+ * | `"Pergola"` | Pergola structure |
+ * | `"Furniture"` | Furniture element |
+ * | `"Facade element"` | Facade element |
+ * | `"Generic mass"` | Generic mass |
+ * | `"Room"` | Room (default for spaces) |
+ * | `"Department"` | Department block |
+ * | `"Building"` | Building envelope |
+ * | `"Revit Import"` | Imported from Revit |
+ * | `"Mass"` | Generic mass type |
+ * | `"Site"` | Site object |
+ */
+export const PluginMassType = z.enum([
+  "Plinth",
+  "Void",
+  "Pergola",
+  "Furniture",
+  "Facade element",
+  "Generic mass",
+  "Room",
+  "Department",
+  "Building",
+  "Revit Import",
+  "Mass",
+  "Site",
+])
+
+/**
+ * Well-known (built-in) department IDs.
+ *
+ * | Value | Department |
+ * |---|---|
+ * | `"DEFAULT"` | Default department |
+ * | `"SITE"` | Site department |
+ * | `"ENVELOPE"` | Envelope department |
+ * | `"CORE"` | Core department |
+ */
+export const PluginWellKnownDepartmentId = z.enum([
+  "DEFAULT",
+  "SITE",
+  "ENVELOPE",
+  "CORE",
+])
+
+/**
+ * Accepted department ID values — either a {@linkcode PluginWellKnownDepartmentId}
+ * or a UUID string for custom (user-created) departments.
+ */
+export const PluginDepartmentId = z.union([
+  PluginWellKnownDepartmentId,
+  z.uuid(),
+])
+
+/**
+ * Arguments for {@linkcode PluginSpaceApi.update}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spaceId` | `string` | The space ID to update |
+ * | `properties` | `object` | Key/value pairs of properties to update (all optional) |
+ * | `properties.room_type` | `string?` | New room type label |
+ * | `properties.massType` | {@linkcode PluginMassType}`?` | New mass type |
+ * | `properties.departmentId` | {@linkcode PluginDepartmentId}`?` | New department ID |
+ */
+export const PluginSpaceUpdateArgs = z.object({
   spaceId: z.string(),
+  properties: z.object({
+    room_type: z.string().optional(),
+    massType: PluginMassType.optional(),
+    spaceType: PluginSpaceType.optional(),
+    departmentId: PluginDepartmentId.optional(),
+  }),
 })
 
-export type PluginSpaceDeleteByIdArgs = z.infer<typeof PluginSpaceDeleteByIdArgs>
+export type PluginSpaceUpdateArgs = z.infer<typeof PluginSpaceUpdateArgs>
+
+/**
+ * Result of {@linkcode PluginSpaceApi.update}.
+ *
+ * Echoes back the `spaceId` and the values of properties that were updated.
+ * Properties that were not included in the update request will be `undefined`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spaceId` | `string` | The space ID that was updated |
+ * | `room_type` | `string?` | Updated room type (if changed) |
+ * | `massType` | `string?` | Updated mass type (if changed) |
+ * | `spaceType` | `string?` | Updated space type (if changed) |
+ * | `departmentId` | `string \| null?` | Updated department ID (if changed) |
+ */
+export const PluginSpaceUpdateResult = z.object({
+  spaceId: z.string(),
+  room_type: z.string().optional(),
+  massType: z.string().optional(),
+  spaceType: z.string().optional(),
+  departmentId: z.string().nullable().optional(),
+})
 
-export type PluginSpaceDeleteByIdResult = void
+export type PluginSpaceUpdateResult = z.infer<typeof PluginSpaceUpdateResult>