@snaptrude/plugin-core 0.9.16 → 0.9.18-edgesetbacks-20261021.1

package/src/api/presentation/diagrams.ts

@@ -1,194 +1,194 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../types"
-
-/**
- * Presentation diagrams — generate program diagrams from the model, and place
- * diagram images onto sheets.
- *
- * {@linkcode PluginPresentationDiagramsApi.generateProgram} runs the Present-mode
- * **Program** action: it reads the project's spaces and departments and creates
- * new layout sheets holding the generated diagram graphics.
- * {@linkcode PluginPresentationDiagramsApi.generateSite} runs the site-diagram
- * flow (location / streetview / climate sheets from the map terrain).
- * {@linkcode PluginPresentationDiagramsApi.place} drops ready diagram images (by
- * URL) onto an existing sheet and returns the created canvas shape ids. All
- * require Present mode to be open. Adjacency data itself is read and computed via
- * `program.adjacency` (see {@linkcode PluginProgramAdjacencyApi}).
- *
- * There is intentionally no `generateAdjacency`: the host's adjacency generator
- * runs its sheet-creation task fire-and-forget internally, so a single call
- * cannot return the sheets it creates. Use the Present-mode Adjacency menu for
- * those, then `place` a pre-rendered adjacency image if you need it via the API.
- *
- * Accessed via `snaptrude.presentation.diagrams`.
- */
-export abstract class PluginPresentationDiagramsApi {
-  constructor() {}
-
-  /**
-   * Generate the program (space + department) diagrams for the current model,
-   * creating new layout sheets.
-   *
-   * Runs the same auto-generation as the Present-mode **Program** action: reads
-   * the project's spaces and departments, lays them out to scale, and creates one
-   * or more new sheets holding the generated diagram graphics. Unlike
-   * {@linkcode PluginPresentationDiagramsApi.place} (which pastes ready image URLs
-   * onto an existing sheet), this generates the graphics from the model and
-   * creates its own sheets. Requires Present mode to be open.
-   *
-   * @returns A {@linkcode PluginPresentationDiagramsGenerateResult} with the
-   *   `sheetIds` of the sheets created.
-   * @throws If Present mode is not open, or the model has no spaces/departments to
-   *   generate from.
-   *
-   * @examplePrompt Generate the program diagrams for this project
-   * @examplePrompt Auto-generate the space and department diagram sheets
-   * @examplePrompt Create the program layout sheets from the model
-   *
-   * # Example
-   * ```ts
-   * const { sheetIds } = await snaptrude.presentation.diagrams.generateProgram()
-   * ```
-   */
-  public abstract generateProgram(): PluginApiReturn<PluginPresentationDiagramsGenerateResult>
-
-  /**
-   * Generate the site diagrams (location, streetview, climate) for the
-   * current model, creating new layout sheets.
-   *
-   * Runs the same auto-generation as the Present-mode site-diagram flow:
-   * each requested type renders its diagram from the project's map terrain
-   * and creates a new sheet holding it. `options.types` selects which
-   * diagrams to generate (default: all three). Generation is tracked
-   * per-proposal — a type whose diagram already exists for the active
-   * proposal is **skipped, not duplicated** (the same semantics as the
-   * mount-time flow; existing site-diagram sheets are never replaced), so
-   * `sheetIds` contains only the sheets created by this call and can be
-   * empty when everything already exists. Requires Present mode to be open
-   * and the project to have a map terrain to generate from.
-   *
-   * @param options - Optional `types` — which site diagrams to generate
-   *   (default: `["location", "streetview", "climate"]`).
-   * @returns A {@linkcode PluginPresentationDiagramsGenerateResult} with the
-   *   `sheetIds` of the sheets created by this call (empty when all requested
-   *   types were already generated).
-   * @throws If Present mode is not open or the project has no map terrain to
-   *   generate from.
-   *
-   * @examplePrompt Generate the site diagrams for this project
-   * @examplePrompt Create the location, streetview and climate sheets
-   * @examplePrompt Add a climate diagram sheet to the presentation
-   *
-   * # Example
-   * ```ts
-   * const { sheetIds } = await snaptrude.presentation.diagrams.generateSite({
-   *   types: ["location", "climate"],
-   * })
-   * ```
-   */
-  public abstract generateSite(options?: {
-    types?: PluginPresentationSiteDiagramType[]
-  }): PluginApiReturn<PluginPresentationDiagramsGenerateResult>
-
-  /**
-   * Place diagram images onto a sheet.
-   *
-   * Drops the given diagram image URLs onto a sheet and returns the ids of the
-   * created canvas shapes. Requires Present mode to be open.
-   *
-   * @param sheetId - The sheet to place onto.
-   * @param urls - Diagram image URLs to place.
-   * @param options - Optional `position` (`{ x, y }`, relative to the sheet)
-   *   for the placed images.
-   * @returns A {@linkcode PluginPresentationDiagramsPlaceResult} with the created
-   *   `shapeIds`.
-   * @throws If Present mode is not open or the sheet id is invalid.
-   *
-   * @examplePrompt Place the adjacency diagram on Sheet 1
-   * @examplePrompt Add the program diagram to the cover sheet
-   * @examplePrompt Drop these diagram images onto the layout
-   *
-   * # Example
-   * ```ts
-   * await snaptrude.presentation.diagrams.place("sheet_1", [
-   *   "https://example.com/program-diagram.png",
-   * ])
-   * ```
-   */
-  public abstract place(
-    sheetId: string,
-    urls: string[],
-    options?: { position?: { x: number; y: number } },
-  ): PluginApiReturn<PluginPresentationDiagramsPlaceResult>
-}
-
-/**
- * Arguments for {@linkcode PluginPresentationDiagramsApi.place}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `sheetId` | `string` | The sheet to place onto |
- * | `urls` | `string[]` | Diagram image URLs |
- * | `position` | `{ x: number; y: number } \| undefined` | Where to place them |
- */
-export const PluginPresentationDiagramsPlaceArgs = z.object({
-  sheetId: z.string(),
-  urls: z.array(z.string()),
-  position: z.object({ x: z.number(), y: z.number() }).optional(),
-})
-export type PluginPresentationDiagramsPlaceArgs = z.infer<
-  typeof PluginPresentationDiagramsPlaceArgs
->
-
-/**
- * Result of {@linkcode PluginPresentationDiagramsApi.place}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `shapeIds` | `string[]` | Ids of the created canvas shapes |
- */
-export const PluginPresentationDiagramsPlaceResult = z.object({
-  shapeIds: z.array(z.string()),
-})
-export type PluginPresentationDiagramsPlaceResult = z.infer<
-  typeof PluginPresentationDiagramsPlaceResult
->
-
-/** A site diagram type — the three diagrams of the Present-mode site flow. */
-export const PluginPresentationSiteDiagramType = z.enum([
-  "location",
-  "streetview",
-  "climate",
-])
-export type PluginPresentationSiteDiagramType = z.infer<
-  typeof PluginPresentationSiteDiagramType
->
-
-/**
- * Arguments for {@linkcode PluginPresentationDiagramsApi.generateSite}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `types` | {@linkcode PluginPresentationSiteDiagramType}`[] \| undefined` | Which site diagrams to generate (default: all three) |
- */
-export const PluginPresentationDiagramsGenerateSiteArgs = z.object({
-  types: z.array(PluginPresentationSiteDiagramType).min(1).optional(),
-})
-export type PluginPresentationDiagramsGenerateSiteArgs = z.infer<
-  typeof PluginPresentationDiagramsGenerateSiteArgs
->
-
-/**
- * Result of {@linkcode PluginPresentationDiagramsApi.generateProgram} and
- * {@linkcode PluginPresentationDiagramsApi.generateSite}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `sheetIds` | `string[]` | Ids of the sheets created by the generator |
- */
-export const PluginPresentationDiagramsGenerateResult = z.object({
-  sheetIds: z.array(z.string()),
-})
-export type PluginPresentationDiagramsGenerateResult = z.infer<
-  typeof PluginPresentationDiagramsGenerateResult
->
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+
+/**
+ * Presentation diagrams — generate program diagrams from the model, and place
+ * diagram images onto sheets.
+ *
+ * {@linkcode PluginPresentationDiagramsApi.generateProgram} runs the Present-mode
+ * **Program** action: it reads the project's spaces and departments and creates
+ * new layout sheets holding the generated diagram graphics.
+ * {@linkcode PluginPresentationDiagramsApi.generateSite} runs the site-diagram
+ * flow (location / streetview / climate sheets from the map terrain).
+ * {@linkcode PluginPresentationDiagramsApi.place} drops ready diagram images (by
+ * URL) onto an existing sheet and returns the created canvas shape ids. All
+ * require Present mode to be open. Adjacency data itself is read and computed via
+ * `program.adjacency` (see {@linkcode PluginProgramAdjacencyApi}).
+ *
+ * There is intentionally no `generateAdjacency`: the host's adjacency generator
+ * runs its sheet-creation task fire-and-forget internally, so a single call
+ * cannot return the sheets it creates. Use the Present-mode Adjacency menu for
+ * those, then `place` a pre-rendered adjacency image if you need it via the API.
+ *
+ * Accessed via `snaptrude.presentation.diagrams`.
+ */
+export abstract class PluginPresentationDiagramsApi {
+  constructor() {}
+
+  /**
+   * Generate the program (space + department) diagrams for the current model,
+   * creating new layout sheets.
+   *
+   * Runs the same auto-generation as the Present-mode **Program** action: reads
+   * the project's spaces and departments, lays them out to scale, and creates one
+   * or more new sheets holding the generated diagram graphics. Unlike
+   * {@linkcode PluginPresentationDiagramsApi.place} (which pastes ready image URLs
+   * onto an existing sheet), this generates the graphics from the model and
+   * creates its own sheets. Requires Present mode to be open.
+   *
+   * @returns A {@linkcode PluginPresentationDiagramsGenerateResult} with the
+   *   `sheetIds` of the sheets created.
+   * @throws If Present mode is not open, or the model has no spaces/departments to
+   *   generate from.
+   *
+   * @examplePrompt Generate the program diagrams for this project
+   * @examplePrompt Auto-generate the space and department diagram sheets
+   * @examplePrompt Create the program layout sheets from the model
+   *
+   * # Example
+   * ```ts
+   * const { sheetIds } = await snaptrude.presentation.diagrams.generateProgram()
+   * ```
+   */
+  public abstract generateProgram(): PluginApiReturn<PluginPresentationDiagramsGenerateResult>
+
+  /**
+   * Generate the site diagrams (location, streetview, climate) for the
+   * current model, creating new layout sheets.
+   *
+   * Runs the same auto-generation as the Present-mode site-diagram flow:
+   * each requested type renders its diagram from the project's map terrain
+   * and creates a new sheet holding it. `options.types` selects which
+   * diagrams to generate (default: all three). Generation is tracked
+   * per-proposal — a type whose diagram already exists for the active
+   * proposal is **skipped, not duplicated** (the same semantics as the
+   * mount-time flow; existing site-diagram sheets are never replaced), so
+   * `sheetIds` contains only the sheets created by this call and can be
+   * empty when everything already exists. Requires Present mode to be open
+   * and the project to have a map terrain to generate from.
+   *
+   * @param options - Optional `types` — which site diagrams to generate
+   *   (default: `["location", "streetview", "climate"]`).
+   * @returns A {@linkcode PluginPresentationDiagramsGenerateResult} with the
+   *   `sheetIds` of the sheets created by this call (empty when all requested
+   *   types were already generated).
+   * @throws If Present mode is not open or the project has no map terrain to
+   *   generate from.
+   *
+   * @examplePrompt Generate the site diagrams for this project
+   * @examplePrompt Create the location, streetview and climate sheets
+   * @examplePrompt Add a climate diagram sheet to the presentation
+   *
+   * # Example
+   * ```ts
+   * const { sheetIds } = await snaptrude.presentation.diagrams.generateSite({
+   *   types: ["location", "climate"],
+   * })
+   * ```
+   */
+  public abstract generateSite(options?: {
+    types?: PluginPresentationSiteDiagramType[]
+  }): PluginApiReturn<PluginPresentationDiagramsGenerateResult>
+
+  /**
+   * Place diagram images onto a sheet.
+   *
+   * Drops the given diagram image URLs onto a sheet and returns the ids of the
+   * created canvas shapes. Requires Present mode to be open.
+   *
+   * @param sheetId - The sheet to place onto.
+   * @param urls - Diagram image URLs to place.
+   * @param options - Optional `position` (`{ x, y }`, relative to the sheet)
+   *   for the placed images.
+   * @returns A {@linkcode PluginPresentationDiagramsPlaceResult} with the created
+   *   `shapeIds`.
+   * @throws If Present mode is not open or the sheet id is invalid.
+   *
+   * @examplePrompt Place the adjacency diagram on Sheet 1
+   * @examplePrompt Add the program diagram to the cover sheet
+   * @examplePrompt Drop these diagram images onto the layout
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.diagrams.place("sheet_1", [
+   *   "https://example.com/program-diagram.png",
+   * ])
+   * ```
+   */
+  public abstract place(
+    sheetId: string,
+    urls: string[],
+    options?: { position?: { x: number; y: number } },
+  ): PluginApiReturn<PluginPresentationDiagramsPlaceResult>
+}
+
+/**
+ * Arguments for {@linkcode PluginPresentationDiagramsApi.place}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetId` | `string` | The sheet to place onto |
+ * | `urls` | `string[]` | Diagram image URLs |
+ * | `position` | `{ x: number; y: number } \| undefined` | Where to place them |
+ */
+export const PluginPresentationDiagramsPlaceArgs = z.object({
+  sheetId: z.string(),
+  urls: z.array(z.string()),
+  position: z.object({ x: z.number(), y: z.number() }).optional(),
+})
+export type PluginPresentationDiagramsPlaceArgs = z.infer<
+  typeof PluginPresentationDiagramsPlaceArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationDiagramsApi.place}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeIds` | `string[]` | Ids of the created canvas shapes |
+ */
+export const PluginPresentationDiagramsPlaceResult = z.object({
+  shapeIds: z.array(z.string()),
+})
+export type PluginPresentationDiagramsPlaceResult = z.infer<
+  typeof PluginPresentationDiagramsPlaceResult
+>
+
+/** A site diagram type — the three diagrams of the Present-mode site flow. */
+export const PluginPresentationSiteDiagramType = z.enum([
+  "location",
+  "streetview",
+  "climate",
+])
+export type PluginPresentationSiteDiagramType = z.infer<
+  typeof PluginPresentationSiteDiagramType
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationDiagramsApi.generateSite}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `types` | {@linkcode PluginPresentationSiteDiagramType}`[] \| undefined` | Which site diagrams to generate (default: all three) |
+ */
+export const PluginPresentationDiagramsGenerateSiteArgs = z.object({
+  types: z.array(PluginPresentationSiteDiagramType).min(1).optional(),
+})
+export type PluginPresentationDiagramsGenerateSiteArgs = z.infer<
+  typeof PluginPresentationDiagramsGenerateSiteArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationDiagramsApi.generateProgram} and
+ * {@linkcode PluginPresentationDiagramsApi.generateSite}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetIds` | `string[]` | Ids of the sheets created by the generator |
+ */
+export const PluginPresentationDiagramsGenerateResult = z.object({
+  sheetIds: z.array(z.string()),
+})
+export type PluginPresentationDiagramsGenerateResult = z.infer<
+  typeof PluginPresentationDiagramsGenerateResult
+>

package/src/api/presentation/drawingContract.ts

@@ -0,0 +1,70 @@
+import * as z from "zod"
+
+/**
+ * Metric architectural scale denominators (`100` means 1:100), the metric
+ * values of the placed view's Scale dropdown.
+ */
+export const METRIC_DRAWING_SCALES = [
+  10, 20, 50, 100, 150, 200, 250, 500, 1000,
+] as const
+
+/**
+ * Imperial detail scale denominators, 1" = 1' (12) to 1/128" = 1' (1536):
+ * `48` is 1/4" = 1', `96` is 1/8" = 1'.
+ */
+export const IMPERIAL_DETAIL_DRAWING_SCALES = [
+  12, 16, 24, 32, 48, 64, 96, 128, 192, 384, 768, 1536,
+] as const
+
+/** Imperial site (engineering) scale denominators, 1" = 10' (120) to 1" = 400' (4800). */
+export const IMPERIAL_SITE_DRAWING_SCALES = [
+  120, 240, 360, 480, 600, 1200, 2400, 3600, 4800,
+] as const
+
+/**
+ * Imperial architectural scale denominators, ascending: the imperial detail
+ * and site values of the placed view's Scale dropdown.
+ */
+export const IMPERIAL_DRAWING_SCALES: readonly number[] = [
+  ...IMPERIAL_DETAIL_DRAWING_SCALES,
+  ...IMPERIAL_SITE_DRAWING_SCALES,
+].sort((a, b) => a - b)
+
+/**
+ * Every standard architectural scale denominator, metric and imperial,
+ * ascending. Drawing and placed-view scale arguments accept only these; the
+ * host may further restrict them to the project's unit system.
+ */
+export const STANDARD_DRAWING_SCALES: readonly number[] = [
+  ...METRIC_DRAWING_SCALES,
+  ...IMPERIAL_DRAWING_SCALES,
+].sort((a, b) => a - b)
+
+const standardScaleSet = new Set<number>(STANDARD_DRAWING_SCALES)
+
+/** A standard architectural scale denominator; anything else is rejected with the allowed list. */
+export const PluginStandardDrawingScale = z
+  .number()
+  .finite()
+  .refine((scale) => standardScaleSet.has(scale), {
+    message: `Scale must be a standard architectural scale denominator in the project's unit system. Metric: ${METRIC_DRAWING_SCALES.join(", ")}; imperial detail: ${IMPERIAL_DETAIL_DRAWING_SCALES.join(", ")}; imperial site: ${IMPERIAL_SITE_DRAWING_SCALES.join(", ")}. Pick the largest standard scale (smallest denominator) at which the view fits its frame or sheet and its room labels stay readable (usually 1:50 to 1:200 for a building plan).`,
+  })
+
+const EXTENSION = /\.(pdf|svg|png|jpe?g)$/i
+// The host appends ".<ext>", so a trailing dot yields "a.pdf..pdf" and trailing
+// whitespace yields "plan .pdf".
+const TRAILING_DOT_OR_SPACE = /[.\s]$/
+
+/**
+ * An export base file name without an extension, not ending in a dot or
+ * whitespace; the host adds `.pdf`, `.svg`, `.png` or `.jpg`.
+ */
+export const PluginExportFileName = z
+  .string()
+  .refine(
+    (name) => !EXTENSION.test(name.trim()) && !TRAILING_DOT_OR_SPACE.test(name),
+    {
+      message:
+        "fileName must be a base name without an extension and not ending in a dot or a space (for example \"Ground Floor Plan\", not \"Ground Floor Plan.pdf\" or \"Ground Floor Plan.\"); the export adds the extension for the format.",
+    },
+  )