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. Accessed via snaptrude.program.labels.

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 (program.departments.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.

All methods are host API calls that return Promises. 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.

At a glance

Method	What it does	Mutates?
list()	List every label with its department, target area and count	—
get(labelId)	One label by id, or null	—
create(items, options?)	Create program rows (and optionally their spaces on the canvas)	✓ (undoable)
setTargetArea(labelId, targetArea, units?)	Set a label's total target area	✓ (undoable)
setTargetCount(labelId, targetCount)	Set a label's target number of units	✓ (undoable)

targetArea is the label's total

targetArea is the target for all units of the label, in the response's units; the per-unit target is targetArea / targetCount. null means no target has been set.

Where units lives

Per the area-units convention, list carries units once on the response envelope. get, setTargetArea and setTargetCount return a bare record, so units sits on the record itself.

Types

PluginProgramLabel

A label (program row) in the active program.

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

PluginProgramLabelRecord

PluginProgramLabel plus units: "ft2" | "m2" — the shape returned by get and the single-record writes.

PluginProgramLabelCreateItem

One label to create via 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 (used with createSpaces)
width	number?	Space width in project length units (used with createSpaces)

Functions

list()

List the labels (program rows) of the active program.

• Returns: { units: "ft2" | "m2"; labels: PluginProgramLabel[] }.

get(labelId)

Get a single label by id.

• Parameters:
  • labelId: string — The label to read.
• Returns: PluginProgramLabelRecord | null.

create(items, options?)

Create labels (program rows), optionally creating their spaces too. 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. Pass createSpaces: true to also instantiate targetCount massing spaces per label on the canvas, laid out automatically — the same path Program Mode's CSV import uses.

• Parameters:
  • items: PluginProgramLabelCreateItem[] — 1–500 labels.
  • options.units: "ft2" | "m2"? — Unit of every targetArea (defaults to the project's area units).
  • options.createSpaces: boolean? — Also create spaces on the canvas (default false).
• Returns: { labelIds: string[]; createdSpaces: boolean } — ids in input order.
• Throws: If an item's departmentId does not exist.

setTargetArea(labelId, targetArea, units?)

Set a label's total target area — the goal the program metrics compare the label's allocated area against.

• Parameters:
  • labelId: string — The label whose target to set.
  • targetArea: number — The total target area (all units), in units.
  • units: "ft2" | "m2"? — Unit of targetArea (defaults to the project's area units).
• Returns: The updated PluginProgramLabelRecord.
• Throws: If no label has the given id.

setTargetCount(labelId, targetCount)

Set a label's target unit count.

• Parameters:
  • labelId: string — The label whose count to set.
  • targetCount: number — A non-negative integer.
• Returns: The updated PluginProgramLabelRecord.
• Throws: If no label has the given id.

Example

Set targets on the non-department rows of a healthcare program, then create a new row.

const { units, labels } = await snaptrude.program.labels.list();
const exam = labels.find((l) => l.name === "Exam Room");
await snaptrude.program.labels.setTargetArea(exam.id, 480, "ft2"); // 4 × 120 sqft
await snaptrude.program.labels.setTargetCount(exam.id, 4);

await snaptrude.program.labels.create(
  [{ name: "Nurse Station", targetArea: 200, targetCount: 1, departmentName: "Clinic" }],
  { units: "ft2" }
);
console.log("targets are reported in", units);