@snaptrude/plugin-core 0.11.0-rc.1 → 1.0.0

package/src/api/presentation/sheets.ts

@@ -1,5 +1,6 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../types"
+import { PluginStandardDrawingScale } from "./drawingContract"
 
 /**
  * Presentation sheets — the layout sheets a presentation is assembled on.
@@ -10,9 +11,16 @@ import { PluginApiReturn } from "../../types"
  *
  * `list`/`get` are reads; the rest mutate and require Present mode to be open:
  * `create` adds a sheet, `place` drops a saved view onto a sheet as a live
- * linked view shape, `rename` relabels a sheet, `delete` removes one, `reorder`
- * moves one in the sheet order, `setActive` navigates to one, and
- * `updatePlacedView` re-renders placed views to the current model.
+ * linked view shape (fitted to that sheet), `placeDrawing` moves an existing
+ * drawing onto a sheet (scaled down to fit by default), `rename` relabels a
+ * sheet, `delete` removes one, `reorder` moves one in the sheet order,
+ * `setActive` navigates to one, and `updatePlacedView` re-renders placed views
+ * to the current model.
+ *
+ * `presentation.drawings.create` never puts a drawing on a sheet: it makes the
+ * drawing beside its source view on the canvas. To put a view on a sheet, call
+ * `place(sheetId, viewId)`; to move a drawing you already made, call
+ * `placeDrawing(sheetId, drawingId)`.
  *
  * Accessed via `snaptrude.presentation.sheets`.
  */
@@ -155,38 +163,75 @@ export abstract class PluginPresentationSheetsApi {
   ): PluginApiReturn<PluginPresentationSheet>
 
   /**
-   * Place a saved view onto a sheet.
+   * Place a saved view onto a sheet. This is the call that puts a view on a
+   * sheet (`presentation.drawings.create` makes a drawing beside its source
+   * view, not on a sheet). When `scale` is omitted the view is fitted to the
+   * target sheet: a 2D or site-plan view is placed at the largest
+   * standard scale at which it fits inside the target sheet's margin, and
+   * never at a larger scale than the normal view drop would pick; a 3D view
+   * has no scale, so it is shrunk evenly to fit instead. This is the same fit
+   * as `placeDrawing`. Omit `position` unless the user asked for a specific
+   * place.
+   * Without a `position` the drawing goes to the sheet centre when that is
+   * free, otherwise to the nearest free spot to the centre inside the margin,
+   * beside the drawings already there; when there is no free spot it is
+   * centred anyway and the result has `overlaps: true`. With a `position` it
+   * is placed as given, and the result has `overlaps: true` when it covers
+   * another drawing, but it is not moved. In both cases only other drawings
+   * count (placed views and their title blocks and labels): text, images and
+   * other shapes on the sheet are ignored. Each call fits one view to the
+   * whole sheet, so a second fitted view often has no free spot: when several
+   * views should share a sheet, pass a `scale` small enough for all of them;
+   * otherwise use `sheets.create` per view. When the result's `overlaps` is
+   * true, move the drawing or put it on its own sheet.
+   * An explicit `scale` is always kept, even when the drawing (title block
+   * included) does not fit inside the sheet's margin at that scale; the result
+   * then has `overflows: true`. When it is true, pass a smaller scale (larger
+   * denominator), omit `scale` to fit, or use a larger sheet.
+   * `scale` must be a standard architectural scale denominator (100 means 1:100)
+   * in the project's unit system; any other value is rejected. Metric: 10, 20, 50,
+   * 100, 150, 200, 250, 500, 1000. Imperial detail: 12, 16, 24, 32, 48, 64, 96, 128,
+   * 192, 384, 768, 1536 (1" = 1' to 1/128" = 1'; 48 is 1/4" = 1', 96 is 1/8" = 1').
+   * Imperial site: 120, 240, 360, 480, 600, 1200, 2400, 3600, 4800 (1" = 10' to
+   * 1" = 400'). Pick the LARGEST standard scale (smallest denominator) at which the
+   * view still fits its frame or sheet and its room labels stay readable: for a
+   * building floor plan that is usually 1:50 to 1:200 (1/4" = 1' to 1/16" = 1').
+   * Never use a site-sized scale (1:500 and up, 1/64" = 1' (768) and smaller,
+   * 1" = 20' (240) and up) for a single building plan unless the user asked for it.
    *
    * Drops the given view onto the sheet through the **native view drop** — the
    * placed shape is a live linked view (the same shape the Present views panel's
    * drag-drop creates), re-rendered from the current model, so
    * {@linkcode PluginPresentationSheetsApi.updatePlacedView} refreshes it later.
-   * 2D and site-plan views are placed at an architectural scale: the closest
-   * standard scale by default (the native auto-fit), or the explicit `scale`
-   * when given — one of the standard values the placed view's Scale dropdown
-   * offers for the project's unit system (metric `10, 20, 50, 100, 150, 200,
-   * 250, 500, 1000`; imperial e.g. `48` for 1/4″ = 1′, `96` for 1/8″ = 1′,
-   * `120` for 1″ = 10′). 3D views have no scale — passing `scale` for one
-   * throws. Requires Present mode to be open.
+   * 2D and site-plan views are placed at an architectural scale: the fitted
+   * standard scale described above by default, or the explicit `scale` when
+   * given (one of the standard values above). 3D views have no scale; passing
+   * `scale` for one throws. Requires Present mode to be open.
    *
    * @param sheetId - The id of the sheet to place onto.
    * @param viewId - The id of the saved view to place.
    * @param options - Optional `position` ({@linkcode PluginSheetPosition}) —
-   *   where to place it (sheet centre when omitted) — `scale` — a standard
-   *   scale value for the project's unit system (2D/site-plan views only;
-   *   auto-fit when omitted) — and `lod` ({@linkcode PluginViewLod}) — the LOD
-   *   of the placed view (default: the product's Design default).
+   *   where to place it (when omitted, the sheet centre or the nearest free
+   *   spot) — and `scale` — a standard scale value for the project's unit system (2D/site-plan views only;
+   *   fitted to the target sheet when omitted).
    * @returns A {@linkcode PluginPresentationSheetsPlaceResult} with the created
-   *   `shapeId`.
+   *   `shapeId`, the `scale` used (`null` for a 3D view), whether the fit
+   *   `rescaled` it, whether it `overlaps` another drawing on the sheet, and
+   *   whether it `overflows` the sheet's margin at an explicit `scale`.
+   *   (Hosts older than the fit return only `shapeId`.)
    * @throws If Present mode is not open, the sheet/view id is invalid, `scale`
    *   is not a standard value for the project's unit system, or `scale` is
-   *   passed for a 3D view.
+   *   passed for a 3D view. `PRECONDITION_FAILED` when the view does not fit
+   *   the sheet even at the smallest standard scale, or the title block alone
+   *   is larger than the sheet's drawable area (use a larger sheet); no
+   *   drawing is left on the sheet.
    *
    * @examplePrompt Place the floor plan on Sheet 1
    * @examplePrompt Add this 3D view to the cover sheet
    * @examplePrompt Drop the site plan onto the layout sheet at 100, 200
    * @examplePrompt Put the Ground Floor view on sheet_1 at 1:100 scale
    * @examplePrompt Place the plan on the cover sheet at quarter-inch scale
+   * @examplePrompt Add a floor plan drawing of each storey to this sheet
    *
    * # Example
    * ```ts
@@ -198,13 +243,75 @@ export abstract class PluginPresentationSheetsApi {
   public abstract place(
     sheetId: string,
     viewId: string,
-    options?: {
-      position?: PluginSheetPosition
-      scale?: number
-      lod?: PluginViewLod
-    },
+    options?: { position?: PluginSheetPosition; scale?: number },
   ): PluginApiReturn<PluginPresentationSheetsPlaceResult>
 
+  /**
+   * Move an existing drawing onto a sheet without copying or regenerating it,
+   * scaled down to fit the sheet when it is too big. `presentation.drawings.create`
+   * leaves a drawing beside its source view, not on a sheet; this is the call
+   * that puts it on one. To place a saved view on a sheet in one call, use
+   * `sheets.place(sheetId, viewId)`, which fits it the same way.
+   * By default (`fit` true or omitted) a drawing larger than the sheet's
+   * drawable area (the sheet inside its margin) is moved to the LARGEST standard
+   * architectural scale at which it fits; a drawing that already fits keeps its
+   * scale, and a drawing is never scaled up. A 3D drawing has no architectural
+   * scale, so it is shrunk uniformly to fit instead. With `fit: false` the scale
+   * is kept and a drawing that does not fit is rejected with an error naming the
+   * drawing, the sheet and the scale, and saying to call `placeDrawing` without
+   * `fit: false` to fit it, or use a larger sheet. When even
+   * the smallest standard scale does not fit, the call is rejected with an error
+   * suggesting a larger sheet size.
+   * Without a `position` the drawing goes to the sheet centre when that is
+   * free, otherwise to the nearest free spot to the centre inside the margin,
+   * beside the drawings already there; when there is no free spot it is
+   * centred anyway and the result has `overlaps: true`. With a `position` it
+   * is placed as given, and the result has `overlaps: true` when it covers
+   * another drawing, but it is not moved. In both cases only other drawings
+   * count (placed views and their title blocks and labels): text, images and
+   * other shapes on the sheet are ignored. Each call fits one drawing to the
+   * whole sheet, so a second fitted drawing often has no free spot: when
+   * several drawings should share a sheet, give them scales small enough for
+   * all of them; otherwise use `sheets.create` per drawing.
+   * The position is sheet-local. The drawing's
+   * stable id remains unchanged; `shapeId` therefore identifies the moved
+   * drawing. The result reports the architectural scale the drawing has on the
+   * sheet and whether this call changed it; a host that reports it also says
+   * whether the drawing `overlaps` another drawing on the sheet (move it or
+   * put it on its own sheet when true).
+   *
+   * @param sheetId - The id of the destination sheet.
+   * @param drawingId - The id of an existing drawing deliverable.
+   * @param options - Optional sheet-local `position` (when omitted, the sheet centre or the nearest free spot)
+   *   and `fit` (default `true`: scale a drawing that does not fit down to fit;
+   *   `false`: keep its scale and reject a drawing that does not fit).
+   * @returns A {@linkcode PluginPresentationSheetsPlaceDrawingResult} with the
+   *   drawing's `shapeId`, the `scale` used (`null` for a 3D drawing),
+   *   `rescaled`, and optionally `overlaps`.
+   * @throws `PRECONDITION_FAILED` if Present mode is closed, the sheet is locked,
+   *   the drawing does not fit with `fit: false`, or it does not fit even at the
+   *   smallest standard scale; `HANDLE_INVALID` if either id is invalid or the
+   *   shape is not a drawing.
+   *
+   * @examplePrompt Move this drawing onto the cover sheet
+   * @examplePrompt Place drawing_1 at the center of sheet_2
+   * @examplePrompt Put the level 2 plan drawing on the Level 2 Plan sheet
+   * @examplePrompt Add the floor plan drawings to this sheet
+   *
+   * # Example
+   * ```ts
+   * const { scale, rescaled } = await snaptrude.presentation.sheets.placeDrawing(
+   *   sheet.id,
+   *   drawing.id,
+   * )
+   * ```
+   */
+  public abstract placeDrawing(
+    sheetId: string,
+    drawingId: string,
+    options?: { position?: PluginSheetPosition; fit?: boolean },
+  ): PluginApiReturn<PluginPresentationSheetsPlaceDrawingResult>
+
   /**
    * Rename a layout sheet.
    *
@@ -413,15 +520,6 @@ export const PluginSheetPosition = z.object({
 })
 export type PluginSheetPosition = z.infer<typeof PluginSheetPosition>
 
-/**
- * The level of detail a placed view renders at: `"design"` (the Design-mode
- * massing representation) or `"bim"` (the detailed BIM representation).
- * Shared by `sheets.place` and `placedViews.*` (defined here because
- * `placedViews` already imports from this module).
- */
-export const PluginViewLod = z.enum(["design", "bim"])
-export type PluginViewLod = z.infer<typeof PluginViewLod>
-
 /** Result of {@linkcode PluginPresentationSheetsApi.list}. */
 export const PluginPresentationSheetsListResult = z.object({
   sheets: z.array(PluginPresentationSheet),
@@ -481,35 +579,82 @@ export type PluginPresentationSheetsSetMarginArgs = z.infer<
  * |---|---|---|
  * | `sheetId` | `string` | The sheet to place onto |
  * | `viewId` | `string` | The saved view to place |
- * | `position` | {@linkcode PluginSheetPosition}` \| undefined` | Where to place it (sheet centre when omitted) |
- * | `scale` | `number \| undefined` | Standard scale value for the project's unit system (2D/site-plan views only; auto-fit to the closest standard scale when omitted) |
- * | `lod` | {@linkcode PluginViewLod}` \| undefined` | LOD of the placed view (default: the product's Design default) |
+ * | `position` | {@linkcode PluginSheetPosition}` \| undefined` | Where to place it (when omitted, the sheet centre or the nearest free spot) |
+ * | `scale` | `number \| undefined` | Standard scale value for the project's unit system (2D/site-plan views only; when omitted, the largest standard scale that fits inside the target sheet's margin, never larger than the normal view drop's) |
  */
 export const PluginPresentationSheetsPlaceArgs = z.object({
   sheetId: z.string(),
   viewId: z.string(),
   position: PluginSheetPosition.optional(),
-  scale: z.number().positive().optional(),
-  lod: PluginViewLod.optional(),
+  scale: PluginStandardDrawingScale.optional(),
 })
 export type PluginPresentationSheetsPlaceArgs = z.infer<
   typeof PluginPresentationSheetsPlaceArgs
 >
 
 /**
- * Result of {@linkcode PluginPresentationSheetsApi.place}.
+ * Arguments for {@linkcode PluginPresentationSheetsApi.placeDrawing}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetId` | `string` | The destination sheet |
+ * | `drawingId` | `string` | The existing drawing to move |
+ * | `position` | {@linkcode PluginSheetPosition}` \| undefined` | Sheet-local position (when omitted, the sheet centre or the nearest free spot) |
+ * | `fit` | `boolean \| undefined` | `true` (default) scales a drawing that does not fit down to fit; `false` keeps its scale and rejects a drawing that does not fit |
+ */
+export const PluginPresentationSheetsPlaceDrawingArgs = z.object({
+  sheetId: z.string().min(1),
+  drawingId: z.string().min(1),
+  position: PluginSheetPosition.optional(),
+  fit: z.boolean().optional(),
+})
+export type PluginPresentationSheetsPlaceDrawingArgs = z.infer<
+  typeof PluginPresentationSheetsPlaceDrawingArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationSheetsApi.place}. The host returns
+ * `scale` and `rescaled` (and `overlaps`, `overflows`); they are optional only
+ * because hosts that predate the fit report `shapeId` alone.
  *
  * | Property | Type | Description |
  * |---|---|---|
  * | `shapeId` | `string` | Id of the created canvas shape |
+ * | `scale` | `number \| null \| undefined` | Architectural scale denominator the view has on the sheet (`null` for a 3D view) |
+ * | `rescaled` | `boolean \| undefined` | Whether the fit changed the view's size from the normal view drop's |
+ * | `overlaps` | `boolean \| undefined` | Whether the placed drawing overlaps another drawing on the sheet (only drawings count, not text, images or other shapes) |
+ * | `overflows` | `boolean \| undefined` | `true` when the drawing, title block included, does not fit inside the sheet's margin at the explicit `scale` passed (the scale is kept); absent otherwise |
  */
 export const PluginPresentationSheetsPlaceResult = z.object({
   shapeId: z.string(),
+  scale: z.number().finite().nullable().optional(),
+  rescaled: z.boolean().optional(),
+  overlaps: z.boolean().optional(),
+  overflows: z.boolean().optional(),
 })
 export type PluginPresentationSheetsPlaceResult = z.infer<
   typeof PluginPresentationSheetsPlaceResult
 >
 
+/**
+ * Result of {@linkcode PluginPresentationSheetsApi.placeDrawing}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | Id of the moved drawing (the drawing id, unchanged) |
+ * | `scale` | `number \| null` | Architectural scale denominator the drawing has on the sheet (`null` for a 3D drawing) |
+ * | `rescaled` | `boolean` | Whether this call changed the drawing's size to fit the sheet |
+ * | `overlaps` | `boolean \| undefined` | Whether the drawing overlaps another drawing on the sheet (only drawings count, not text, images or other shapes) |
+ */
+export const PluginPresentationSheetsPlaceDrawingResult =
+  PluginPresentationSheetsPlaceResult.omit({ overflows: true }).extend({
+    scale: z.number().finite().nullable(),
+    rescaled: z.boolean(),
+  })
+export type PluginPresentationSheetsPlaceDrawingResult = z.infer<
+  typeof PluginPresentationSheetsPlaceDrawingResult
+>
+
 /**
  * Arguments for {@linkcode PluginPresentationSheetsApi.rename}.
  *