@snaptrude/plugin-core 0.9.8 → 0.9.9

package/dist/api/program/labels.d.ts

@@ -0,0 +1,355 @@
+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 declare 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)
+     * ```
+     */
+    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)
+     * ```
+     */
+    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" },
+     * )
+     * ```
+     */
+    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")
+     * ```
+     */
+    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)
+     * ```
+     */
+    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 declare const PluginProgramLabel: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    color: z.ZodString;
+    departmentId: z.ZodString;
+    targetArea: z.ZodNullable<z.ZodNumber>;
+    targetCount: z.ZodNumber;
+    storey: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type PluginProgramLabel = z.infer<typeof PluginProgramLabel>;
+/** A bare label record carrying its area `units` (per the area-units convention). */
+export declare const PluginProgramLabelRecord: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    color: z.ZodString;
+    departmentId: z.ZodString;
+    targetArea: z.ZodNullable<z.ZodNumber>;
+    targetCount: z.ZodNumber;
+    storey: z.ZodNullable<z.ZodNumber>;
+    units: z.ZodEnum<{
+        ft2: "ft2";
+        m2: "m2";
+    }>;
+}, z.core.$strip>;
+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 declare const PluginProgramLabelsListResult: z.ZodObject<{
+    units: z.ZodEnum<{
+        ft2: "ft2";
+        m2: "m2";
+    }>;
+    labels: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        color: z.ZodString;
+        departmentId: z.ZodString;
+        targetArea: z.ZodNullable<z.ZodNumber>;
+        targetCount: z.ZodNumber;
+        storey: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type PluginProgramLabelsListResult = z.infer<typeof PluginProgramLabelsListResult>;
+/** Arguments for {@linkcode PluginProgramLabelsApi.get}. */
+export declare const PluginProgramLabelsGetArgs: z.ZodObject<{
+    labelId: z.ZodString;
+}, z.core.$strip>;
+export type PluginProgramLabelsGetArgs = z.infer<typeof PluginProgramLabelsGetArgs>;
+/** Result of {@linkcode PluginProgramLabelsApi.get} — the record with `units`, or `null`. */
+export declare const PluginProgramLabelsGetResult: z.ZodNullable<z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    color: z.ZodString;
+    departmentId: z.ZodString;
+    targetArea: z.ZodNullable<z.ZodNumber>;
+    targetCount: z.ZodNumber;
+    storey: z.ZodNullable<z.ZodNumber>;
+    units: z.ZodEnum<{
+        ft2: "ft2";
+        m2: "m2";
+    }>;
+}, z.core.$strip>>;
+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 declare const PluginProgramLabelCreateItem: z.ZodObject<{
+    name: z.ZodString;
+    targetArea: z.ZodOptional<z.ZodNumber>;
+    targetCount: z.ZodOptional<z.ZodNumber>;
+    departmentId: z.ZodOptional<z.ZodString>;
+    departmentName: z.ZodOptional<z.ZodString>;
+    color: z.ZodOptional<z.ZodString>;
+    storey: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+    width: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type PluginProgramLabelCreateItem = z.infer<typeof PluginProgramLabelCreateItem>;
+/** Maximum items per {@linkcode PluginProgramLabelsApi.create} call. */
+export declare 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 declare const PluginProgramLabelsCreateArgs: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        targetArea: z.ZodOptional<z.ZodNumber>;
+        targetCount: z.ZodOptional<z.ZodNumber>;
+        departmentId: z.ZodOptional<z.ZodString>;
+        departmentName: z.ZodOptional<z.ZodString>;
+        color: z.ZodOptional<z.ZodString>;
+        storey: z.ZodOptional<z.ZodNumber>;
+        height: z.ZodOptional<z.ZodNumber>;
+        width: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    units: z.ZodOptional<z.ZodEnum<{
+        ft2: "ft2";
+        m2: "m2";
+    }>>;
+    createSpaces: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+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 declare const PluginProgramLabelsCreateResult: z.ZodObject<{
+    labelIds: z.ZodArray<z.ZodString>;
+    createdSpaces: z.ZodBoolean;
+}, z.core.$strip>;
+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 declare const PluginProgramLabelsSetTargetAreaArgs: z.ZodObject<{
+    labelId: z.ZodString;
+    targetArea: z.ZodNumber;
+    units: z.ZodOptional<z.ZodEnum<{
+        ft2: "ft2";
+        m2: "m2";
+    }>>;
+}, z.core.$strip>;
+export type PluginProgramLabelsSetTargetAreaArgs = z.infer<typeof PluginProgramLabelsSetTargetAreaArgs>;
+/** Result of {@linkcode PluginProgramLabelsApi.setTargetArea} — the updated record with `units`. */
+export declare const PluginProgramLabelsSetTargetAreaResult: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    color: z.ZodString;
+    departmentId: z.ZodString;
+    targetArea: z.ZodNullable<z.ZodNumber>;
+    targetCount: z.ZodNumber;
+    storey: z.ZodNullable<z.ZodNumber>;
+    units: z.ZodEnum<{
+        ft2: "ft2";
+        m2: "m2";
+    }>;
+}, z.core.$strip>;
+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 declare const PluginProgramLabelsSetTargetCountArgs: z.ZodObject<{
+    labelId: z.ZodString;
+    targetCount: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginProgramLabelsSetTargetCountArgs = z.infer<typeof PluginProgramLabelsSetTargetCountArgs>;
+/** Result of {@linkcode PluginProgramLabelsApi.setTargetCount} — the updated record with `units`. */
+export declare const PluginProgramLabelsSetTargetCountResult: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    color: z.ZodString;
+    departmentId: z.ZodString;
+    targetArea: z.ZodNullable<z.ZodNumber>;
+    targetCount: z.ZodNumber;
+    storey: z.ZodNullable<z.ZodNumber>;
+    units: z.ZodEnum<{
+        ft2: "ft2";
+        m2: "m2";
+    }>;
+}, z.core.$strip>;
+export type PluginProgramLabelsSetTargetCountResult = z.infer<typeof PluginProgramLabelsSetTargetCountResult>;
+//# sourceMappingURL=labels.d.ts.map

package/dist/api/program/labels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"labels.d.ts","sourceRoot":"","sources":["../../../src/api/program/labels.ts"],"names":[],"mappings":"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"}