@snaptrude/plugin-core 0.0.0-dev-20260911064951 → 0.0.0-dev-20260921132444

package/src/api/program/index.ts

@@ -7,22 +7,26 @@ 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 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.
+ * 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 and read it back
+ * - {@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
@@ -32,6 +36,10 @@ import { PluginProgramAreasApi } from "./areas"
 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}. */
@@ -40,7 +48,7 @@ export abstract class PluginProgramApi {
   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}. */
+  /** 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
@@ -61,3 +69,5 @@ export * from "./site"
 export * from "./cores"
 export * from "./classification"
 export * from "./areas"
+export * from "./metadata"
+export * from "./labels"

package/src/api/program/labels.ts

@@ -0,0 +1,332 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { PluginAreaUnit } from "./metrics"
+
+/**
+ * Program labels — the **program rows** of the active program: each label is a
+ * named space type (e.g. "Exam Room", "Nurse Station") inside a department,
+ * carrying an area **target** and a unit **count** target.
+ *
+ * Labels are the non-department planning entities of program mode. A
+ * department groups labels; a label groups the spaces (masses) that realize it.
+ * Target areas live on **departments** ({@linkcode PluginProgramDepartmentsApi.setTargetArea})
+ * and on **labels** (this namespace) — an individual space carries no target of
+ * its own; it inherits its label's `targetArea / targetCount`. Program Blocks
+ * (spaces whose space type is "Program Block") are likewise targeted through
+ * their label.
+ *
+ * `targetArea` is the label's **total** target (all units), in the response's
+ * `units`; the per-unit target is `targetArea / targetCount`.
+ *
+ * Reads never throw for a miss (`get` returns `null`, `list` returns `[]`).
+ * Writes are undoable and autosaved; when the project has proposals they write
+ * the **active proposal's** targets.
+ *
+ * Accessed via `snaptrude.program.labels`.
+ */
+export abstract class PluginProgramLabelsApi {
+  constructor() {}
+
+  /**
+   * List the labels (program rows) of the active program.
+   *
+   * @returns A {@linkcode PluginProgramLabelsListResult} with `units` and a
+   *   `labels` array (empty when the project has none).
+   *
+   * @examplePrompt List all the program rows with their target areas
+   * @examplePrompt What space labels are in the program and how many of each?
+   * @examplePrompt Show every label with its department and target
+   *
+   * # Example
+   * ```ts
+   * const { units, labels } = await snaptrude.program.labels.list()
+   * for (const l of labels) console.log(l.name, l.targetArea, units, l.targetCount)
+   * ```
+   */
+  public abstract list(): PluginApiReturn<PluginProgramLabelsListResult>
+
+  /**
+   * Get a single label by id.
+   *
+   * @param labelId - The id of the label to read.
+   * @returns The matching {@linkcode PluginProgramLabelRecord} (with `units`), or
+   *   `null` if no label has that id.
+   *
+   * @examplePrompt Get the label with id lbl_12
+   * @examplePrompt What is the target area of this program row?
+   *
+   * # Example
+   * ```ts
+   * const label = await snaptrude.program.labels.get("lbl_12")
+   * if (label) console.log(label.name, label.targetArea, label.units)
+   * ```
+   */
+  public abstract get(
+    labelId: string,
+  ): PluginApiReturn<PluginProgramLabelsGetResult>
+
+  /**
+   * Create labels (program rows), optionally creating their spaces too.
+   *
+   * Each item names a label and its targets. A label is unique per
+   * (`name`, department); an item matching an existing label **updates** that
+   * label's targets instead of duplicating it. Unknown departments are created
+   * by name when `departmentName` is given; omit both department fields for the
+   * Default department.
+   *
+   * By default only the program rows are created (targets to plan against).
+   * Pass `createSpaces: true` to also instantiate `targetCount` massing spaces
+   * per label on the canvas, laid out automatically — the same path Program
+   * Mode's CSV/Interpret import uses.
+   *
+   * @param items - The labels to create (1–500).
+   * @param options - Optional `units` for every `targetArea` (defaults to the
+   *   project's area units) and `createSpaces` (default `false`).
+   * @returns A {@linkcode PluginProgramLabelsCreateResult} with the created or
+   *   updated label ids, in input order.
+   * @throws If an item's `departmentId` does not exist.
+   *
+   * @examplePrompt Add program rows for 4 exam rooms of 120 sqft each
+   * @examplePrompt Create the labels from this interpreted program
+   * @examplePrompt Add an Office label with a 2000 sqft target to the Admin department
+   * @examplePrompt Create program rows and their spaces on the canvas
+   *
+   * # Example
+   * ```ts
+   * const { labelIds } = await snaptrude.program.labels.create(
+   *   [{ name: "Exam Room", targetArea: 480, targetCount: 4, departmentName: "Clinic" }],
+   *   { units: "ft2" },
+   * )
+   * ```
+   */
+  public abstract create(
+    items: PluginProgramLabelCreateItem[],
+    options?: { units?: PluginAreaUnit; createSpaces?: boolean },
+  ): PluginApiReturn<PluginProgramLabelsCreateResult>
+
+  /**
+   * Set a label's total target area.
+   *
+   * The goal the program metrics compare the label's allocated area against.
+   * Pass `units` to say what unit `targetArea` is in; it defaults to the
+   * project's area units. Read it back with {@linkcode PluginProgramLabelsApi.get}.
+   *
+   * @param labelId - The id of the label whose target to set.
+   * @param targetArea - The total target area (all units), in `units`.
+   * @param units - Unit of `targetArea` (defaults to the project's area units).
+   * @returns The updated {@linkcode PluginProgramLabelRecord} with its `units`.
+   * @throws If no label has the given id.
+   *
+   * @examplePrompt Set the Exam Room target area to 480 sqft
+   * @examplePrompt Give the Corridor program row a 150 sqm target
+   * @examplePrompt Update the area target for label lbl_12
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.program.labels.setTargetArea("lbl_12", 480, "ft2")
+   * ```
+   */
+  public abstract setTargetArea(
+    labelId: string,
+    targetArea: number,
+    units?: PluginAreaUnit,
+  ): PluginApiReturn<PluginProgramLabelsSetTargetAreaResult>
+
+  /**
+   * Set a label's target unit count (how many of this space the program calls for).
+   *
+   * @param labelId - The id of the label whose count to set.
+   * @param targetCount - The target number of units (a non-negative integer).
+   * @returns The updated {@linkcode PluginProgramLabelRecord} with its `units`.
+   * @throws If no label has the given id.
+   *
+   * @examplePrompt Set the Exam Room count to 6
+   * @examplePrompt The program needs 12 patient rooms — update the count
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.program.labels.setTargetCount("lbl_12", 6)
+   * ```
+   */
+  public abstract setTargetCount(
+    labelId: string,
+    targetCount: number,
+  ): PluginApiReturn<PluginProgramLabelsSetTargetCountResult>
+}
+
+/**
+ * A label (program row) in the active program. `targetArea` is the label's
+ * **total** target in the enclosing response's `units`.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Stable label id |
+ * | `name` | `string` | Label (space type) name |
+ * | `color` | `string` | CSS hex color string |
+ * | `departmentId` | `string` | Id of the department the label belongs to |
+ * | `targetArea` | `number \| null` | Total target area (all units), or `null` when no target is set |
+ * | `targetCount` | `number` | Target number of units (`0` when unset) |
+ * | `storey` | `number \| null` | Default storey new spaces of this label are placed on |
+ */
+export const PluginProgramLabel = z.object({
+  id: z.string(),
+  name: z.string(),
+  color: z.string(),
+  departmentId: z.string(),
+  targetArea: z.number().nullable(),
+  targetCount: z.number(),
+  storey: z.number().nullable(),
+})
+export type PluginProgramLabel = z.infer<typeof PluginProgramLabel>
+
+/** A bare label record carrying its area `units` (per the area-units convention). */
+export const PluginProgramLabelRecord = PluginProgramLabel.extend({
+  units: PluginAreaUnit,
+})
+export type PluginProgramLabelRecord = z.infer<typeof PluginProgramLabelRecord>
+
+/**
+ * Result of {@linkcode PluginProgramLabelsApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `units` | `"ft2" \| "m2"` | The unit every `targetArea` below is reported in |
+ * | `labels` | {@linkcode PluginProgramLabel}`[]` | All labels in the active program |
+ */
+export const PluginProgramLabelsListResult = z.object({
+  units: PluginAreaUnit,
+  labels: z.array(PluginProgramLabel),
+})
+export type PluginProgramLabelsListResult = z.infer<
+  typeof PluginProgramLabelsListResult
+>
+
+/** Arguments for {@linkcode PluginProgramLabelsApi.get}. */
+export const PluginProgramLabelsGetArgs = z.object({
+  labelId: z.string(),
+})
+export type PluginProgramLabelsGetArgs = z.infer<
+  typeof PluginProgramLabelsGetArgs
+>
+
+/** Result of {@linkcode PluginProgramLabelsApi.get} — the record with `units`, or `null`. */
+export const PluginProgramLabelsGetResult = PluginProgramLabelRecord.nullable()
+export type PluginProgramLabelsGetResult = z.infer<
+  typeof PluginProgramLabelsGetResult
+>
+
+/**
+ * One label to create via {@linkcode PluginProgramLabelsApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `name` | `string` | Label (space type) name |
+ * | `targetArea` | `number?` | Total target area (all units), in the call's `units` |
+ * | `targetCount` | `number?` | Target number of units (default `1`) |
+ * | `departmentId` | `string?` | Existing department to file the label under |
+ * | `departmentName` | `string?` | Department by name — created when it does not exist (ignored when `departmentId` is given) |
+ * | `color` | `string?` | CSS hex color (a light color is generated when omitted) |
+ * | `storey` | `number?` | Storey for spaces of this label (default `1`) |
+ * | `height` | `number?` | Space height in project length units (for `createSpaces`) |
+ * | `width` | `number?` | Space width in project length units (for `createSpaces`) |
+ */
+export const PluginProgramLabelCreateItem = z.object({
+  name: z.string().trim().min(1),
+  targetArea: z.number().finite().nonnegative().optional(),
+  targetCount: z.number().int().nonnegative().optional(),
+  departmentId: z.string().optional(),
+  departmentName: z.string().optional(),
+  color: z.string().optional(),
+  storey: z.number().int().optional(),
+  height: z.number().finite().positive().optional(),
+  width: z.number().finite().positive().optional(),
+})
+export type PluginProgramLabelCreateItem = z.infer<
+  typeof PluginProgramLabelCreateItem
+>
+
+/** Maximum items per {@linkcode PluginProgramLabelsApi.create} call. */
+export const PLUGIN_PROGRAM_LABELS_BATCH_LIMIT = 500
+
+/**
+ * Arguments for {@linkcode PluginProgramLabelsApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `items` | {@linkcode PluginProgramLabelCreateItem}`[]` | 1–500 labels |
+ * | `units` | `"ft2" \| "m2"?` | Unit of every `targetArea` (defaults to the project's area units) |
+ * | `createSpaces` | `boolean?` | Also create `targetCount` spaces per label on the canvas (default `false`) |
+ */
+export const PluginProgramLabelsCreateArgs = z.object({
+  items: z
+    .array(PluginProgramLabelCreateItem)
+    .min(1)
+    .max(PLUGIN_PROGRAM_LABELS_BATCH_LIMIT),
+  units: PluginAreaUnit.optional(),
+  createSpaces: z.boolean().optional(),
+})
+export type PluginProgramLabelsCreateArgs = z.infer<
+  typeof PluginProgramLabelsCreateArgs
+>
+
+/**
+ * Result of {@linkcode PluginProgramLabelsApi.create}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `labelIds` | `string[]` | The created (or updated) label ids, in input order |
+ * | `createdSpaces` | `boolean` | Whether spaces were also created on the canvas |
+ */
+export const PluginProgramLabelsCreateResult = z.object({
+  labelIds: z.array(z.string()),
+  createdSpaces: z.boolean(),
+})
+export type PluginProgramLabelsCreateResult = z.infer<
+  typeof PluginProgramLabelsCreateResult
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramLabelsApi.setTargetArea}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `labelId` | `string` | The label whose target to set |
+ * | `targetArea` | `number` | Total target area, in `units` |
+ * | `units` | `"ft2" \| "m2"?` | Unit of `targetArea` (defaults to the project's area units) |
+ */
+export const PluginProgramLabelsSetTargetAreaArgs = z.object({
+  labelId: z.string(),
+  targetArea: z.number().finite().nonnegative(),
+  units: PluginAreaUnit.optional(),
+})
+export type PluginProgramLabelsSetTargetAreaArgs = z.infer<
+  typeof PluginProgramLabelsSetTargetAreaArgs
+>
+
+/** Result of {@linkcode PluginProgramLabelsApi.setTargetArea} — the updated record with `units`. */
+export const PluginProgramLabelsSetTargetAreaResult = PluginProgramLabelRecord
+export type PluginProgramLabelsSetTargetAreaResult = z.infer<
+  typeof PluginProgramLabelsSetTargetAreaResult
+>
+
+/**
+ * Arguments for {@linkcode PluginProgramLabelsApi.setTargetCount}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `labelId` | `string` | The label whose count to set |
+ * | `targetCount` | `number` | Target number of units (non-negative integer) |
+ */
+export const PluginProgramLabelsSetTargetCountArgs = z.object({
+  labelId: z.string(),
+  targetCount: z.number().int().nonnegative(),
+})
+export type PluginProgramLabelsSetTargetCountArgs = z.infer<
+  typeof PluginProgramLabelsSetTargetCountArgs
+>
+
+/** Result of {@linkcode PluginProgramLabelsApi.setTargetCount} — the updated record with `units`. */
+export const PluginProgramLabelsSetTargetCountResult = PluginProgramLabelRecord
+export type PluginProgramLabelsSetTargetCountResult = z.infer<
+  typeof PluginProgramLabelsSetTargetCountResult
+>