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

package/src/api/presentation/placedViews.ts

@@ -1,6 +1,7 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../types"
-import { PluginSheetPosition, PluginViewLod } from "./sheets"
+import { PluginSheetPosition } from "./sheets"
+import { PluginStandardDrawingScale } from "./drawingContract"
 
 /**
  * Placed views — the view shapes already laid out on the Present canvas.
@@ -141,14 +142,21 @@ export abstract class PluginPresentationPlacedViewsApi {
 
   /**
    * Set a placed view's architectural scale.
+   * `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.
    *
    * Applies a standard architectural scale — the same write the placed view's
    * Scale dropdown performs. The view (and its labels) is resized about its
-   * top-left corner so it prints at the given scale. `scale` must be one of
-   * the standard values 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′) — the same validation as
-   * `sheets.place`. 3D views have no architectural scale — calling this on
+   * top-left corner so it prints at the given scale (the same validation as
+   * `sheets.place`). 3D views have no architectural scale — calling this on
    * one throws. Requires Present mode to be open.
    *
    * @param shapeId - The placed view shape to set the scale of.
@@ -613,23 +621,6 @@ export abstract class PluginPresentationPlacedViewsApi {
     shapeId: string,
     enabled: boolean,
   ): PluginApiReturn<void>
-
-  /**
-   * Set the level of detail a placed view renders at — `"design"` (the
-   * Design-mode massing representation) or `"bim"` (the detailed BIM
-   * representation). Views only. Undoable. Requires Present mode to be open.
-   *
-   * @param shapeId - The placed view shape.
-   * @param lod - Target level of detail.
-   * @throws If Present mode is not open or `shapeId` is not a placed view.
-   *
-   * @examplePrompt Switch this placed view to the BIM level of detail
-   * @examplePrompt Show the massing version of the placed plan
-   */
-  public abstract setLod(
-    shapeId: string,
-    lod: PluginViewLod,
-  ): PluginApiReturn<void>
 }
 
 /** A point in crop space — fractions (0–1) of the uncropped view. */
@@ -674,8 +665,6 @@ export type PluginPlacedViewCrop = z.infer<typeof PluginPlacedViewCrop>
  * | `rotation` | `number` | Rotation in radians, `[0, 2π)` (nonzero only for 3D views — 2D views cannot rotate; set with `setRotation`) |
  * | `crop` | {@linkcode PluginPlacedViewCrop}` \| null` | Crop window (`null` when uncropped) |
  * | `isUnlinked` | `boolean` | Whether the source proposal was removed (an unlinked view no longer refreshes) |
- * | `lod` | {@linkcode PluginViewLod}? | Level of detail the view renders at (`"design"` massing / `"bim"` detail); absent on views that predate LOD variants (set with `setLod`) |
- * | `inactiveBuildingMask` | `boolean`? | Whether inactive proposal buildings are masked (the `setMask` toggle); absent when never set (masked by default) |
  */
 export const PluginPlacedView = z.object({
   shapeId: z.string(),
@@ -689,8 +678,6 @@ export const PluginPlacedView = z.object({
   rotation: z.number(),
   crop: PluginPlacedViewCrop.nullable(),
   isUnlinked: z.boolean(),
-  lod: PluginViewLod.optional(),
-  inactiveBuildingMask: z.boolean().optional(),
 })
 export type PluginPlacedView = z.infer<typeof PluginPlacedView>
 
@@ -762,7 +749,7 @@ export type PluginPresentationPlacedViewsScaleArgs = z.infer<
  */
 export const PluginPresentationPlacedViewsSetScaleArgs = z.object({
   shapeId: z.string(),
-  scale: z.number().positive(),
+  scale: PluginStandardDrawingScale,
 })
 export type PluginPresentationPlacedViewsSetScaleArgs = z.infer<
   typeof PluginPresentationPlacedViewsSetScaleArgs
@@ -815,11 +802,28 @@ export const PluginViewSettingCategory = z.enum([
   "Envelope",
   "Facade/Mass",
   "Dimension",
+  "Grid",
+  "Walls",
+  "Columns",
+  "Beams",
+  "Doors",
+  "Windows",
+  "Floors",
+  "Slabs",
+  "Roofs",
+  "Ceilings",
+  "Staircase",
+  "Furniture",
+  "Families",
+  "Underlay",
+  "Overlay",
   "Reference Line",
   "Adjacency Line",
   "Landscape elements",
 ])
-export type PluginViewSettingCategory = z.infer<typeof PluginViewSettingCategory>
+export type PluginViewSettingCategory = z.infer<
+  typeof PluginViewSettingCategory
+>
 
 /** The 7 line dash styles (mirrors the host's LINE_STYLES). */
 export const PluginViewLineStyle = z.enum([
@@ -845,7 +849,7 @@ export type PluginViewLineStyle = z.infer<typeof PluginViewLineStyle>
  * | `lineStyle` | {@linkcode PluginViewLineStyle}? | Dash pattern |
  * | `lineColor` | `string`? | Line color, 6-digit hex (`#` optional) |
  * | `dashLength` | `number`? | Dash-length multiplier (> 0; `1` = default) |
- * | `lineWidth` | `number`? | Single line weight in mm (categories without cut/projection) |
+ * | `lineWidth` | `number`? | Single line weight in mm (Dimension: 0.05–0.7; otherwise non-negative) |
  * | `cutWidth` | `number`? | Cut-line weight in mm |
  * | `projectionWidth` | `number`? | Projection-line weight in mm |
  * | `treeLineWidth` | `number`? | Tree line weight in mm (Landscape) |
@@ -878,8 +882,13 @@ export const PluginPlacedViewStylePatch = z
     colorMode: z
       .string()
       .refine(
-        (v) => ["department", "texture", "monochrome"].includes(v) || v.startsWith("tag:"),
-        { message: "colorMode must be department, texture, monochrome, or tag:<tagCategoryId>" },
+        (v) =>
+          ["department", "texture", "monochrome"].includes(v) ||
+          v.startsWith("tag:"),
+        {
+          message:
+            "colorMode must be department, texture, monochrome, or tag:<tagCategoryId>",
+        },
       )
       .optional(),
     opacity: z.number().finite().min(0).max(100).optional(),
@@ -891,13 +900,42 @@ export const PluginPlacedViewStylePatch = z
     viewStyle: z.enum(["NONE", "FILLET", "BUBBLE"]).optional(),
     radius: z.number().finite().min(0).optional(),
     inset: z.number().finite().min(0).optional(),
+    // Dimension lengths are plotted paper millimetres, independent of drawing scale.
+    markerKind: z
+      .enum(["architecturalTick", "openArrow", "closedArrow"])
+      .optional(),
+    markerSize: z.number().finite().min(0.5).max(6).optional(),
+    extensionLineVisible: z.boolean().optional(),
+    extensionLineStyle: PluginViewLineStyle.optional(),
+    extensionGap: z.number().finite().min(0).max(10).optional(),
+    extensionOvershoot: z.number().finite().min(0).max(10).optional(),
+    textColor: z
+      .string()
+      .regex(/^(inherit|#[0-9a-fA-F]{6})$/)
+      .optional(),
+    textGap: z.number().finite().min(0).max(10).optional(),
+    textPlacement: z.literal("above").optional(),
+    textMask: z.boolean().optional(),
+    textMaskColor: z
+      .string()
+      .regex(/^#[0-9a-fA-F]{6}$/)
+      .optional(),
+    textMaskPadding: z.number().finite().min(0).max(5).optional(),
   })
   .strict()
-  .refine((p) => Object.keys(p).length > 0, { message: "patch must set at least one setting" })
-export type PluginPlacedViewStylePatch = z.infer<typeof PluginPlacedViewStylePatch>
+  .refine((p) => Object.keys(p).length > 0, {
+    message: "patch must set at least one setting",
+  })
+export type PluginPlacedViewStylePatch = z.infer<
+  typeof PluginPlacedViewStylePatch
+>
 
 /** Label types that carry typography in a category's Text tab. */
-export const PluginViewLabelType = z.enum(["objectLabels", "department", "areas"])
+export const PluginViewLabelType = z.enum([
+  "objectLabels",
+  "department",
+  "areas",
+])
 export type PluginViewLabelType = z.infer<typeof PluginViewLabelType>
 
 /** Typography patch for one label type. `fontSize` is in px. */
@@ -906,7 +944,10 @@ const PluginViewFontVariantPatch = z
     fontFamily: z.string().min(1).optional(),
     fontWeight: z
       .string()
-      .regex(/^\d{3}$/, 'fontWeight must be a numeric string like "400" or "700"')
+      .regex(
+        /^\d{3}$/,
+        'fontWeight must be a numeric string like "400" or "700"',
+      )
       .optional(),
     fontStyle: z.enum(["normal", "italic"]).optional(),
     fontSize: z.number().finite().positive().max(200).optional(),
@@ -931,8 +972,12 @@ export const PluginPlacedViewFontStylesPatch = z
     areas: PluginViewFontVariantPatch.optional(),
   })
   .strict()
-  .refine((p) => Object.keys(p).length > 0, { message: "patch must set at least one field" })
-export type PluginPlacedViewFontStylesPatch = z.infer<typeof PluginPlacedViewFontStylesPatch>
+  .refine((p) => Object.keys(p).length > 0, {
+    message: "patch must set at least one field",
+  })
+export type PluginPlacedViewFontStylesPatch = z.infer<
+  typeof PluginPlacedViewFontStylesPatch
+>
 
 /** Resolved font styles for one label type (fontSize in px). */
 export type PluginViewFontVariant = {
@@ -982,12 +1027,25 @@ export type PluginPlacedViewStylesResult = {
 }
 
 /** Arguments for {@link PluginPresentationPlacedViewsApi.updateStyles}. */
-export const PluginPlacedViewsUpdateStylesArgs = z.object({
-  shapeId: z.string().min(1),
-  category: PluginViewSettingCategory,
-  patch: PluginPlacedViewStylePatch,
-})
-export type PluginPlacedViewsUpdateStylesArgs = z.infer<typeof PluginPlacedViewsUpdateStylesArgs>
+export const PluginPlacedViewsUpdateStylesArgs = z
+  .object({
+    shapeId: z.string().min(1),
+    category: PluginViewSettingCategory,
+    patch: PluginPlacedViewStylePatch,
+  })
+  .refine(
+    ({ category, patch }) =>
+      category !== "Dimension" ||
+      patch.lineWidth === undefined ||
+      (patch.lineWidth >= 0.05 && patch.lineWidth <= 0.7),
+    {
+      message: "Dimension lineWidth must be between 0.05 and 0.7 paper mm",
+      path: ["patch", "lineWidth"],
+    },
+  )
+export type PluginPlacedViewsUpdateStylesArgs = z.infer<
+  typeof PluginPlacedViewsUpdateStylesArgs
+>
 
 /** Arguments for {@link PluginPresentationPlacedViewsApi.updateFontStyles}. */
 export const PluginPlacedViewsUpdateFontStylesArgs = z.object({
@@ -1032,7 +1090,9 @@ export const PluginPlacedViewsMoveLabelArgs = z.object({
   labelId: z.string().min(1),
   position: PluginSheetPosition,
 })
-export type PluginPlacedViewsMoveLabelArgs = z.infer<typeof PluginPlacedViewsMoveLabelArgs>
+export type PluginPlacedViewsMoveLabelArgs = z.infer<
+  typeof PluginPlacedViewsMoveLabelArgs
+>
 
 /** Arguments for {@link PluginPresentationPlacedViewsApi.setLabelHidden}. */
 export const PluginPlacedViewsSetLabelHiddenArgs = z.object({
@@ -1102,14 +1162,18 @@ export const PluginPlacedViewsMoveShapeArgs = z.object({
   position: PluginSheetPosition,
   sheetId: z.string().optional(),
 })
-export type PluginPlacedViewsMoveShapeArgs = z.infer<typeof PluginPlacedViewsMoveShapeArgs>
+export type PluginPlacedViewsMoveShapeArgs = z.infer<
+  typeof PluginPlacedViewsMoveShapeArgs
+>
 
 /** Arguments for {@link PluginPresentationPlacedViewsApi.resizeShape}. */
 export const PluginPlacedViewsResizeShapeArgs = z.object({
   shapeId: z.string().min(1),
   factor: z.number().finite().min(0.01).max(100),
 })
-export type PluginPlacedViewsResizeShapeArgs = z.infer<typeof PluginPlacedViewsResizeShapeArgs>
+export type PluginPlacedViewsResizeShapeArgs = z.infer<
+  typeof PluginPlacedViewsResizeShapeArgs
+>
 
 /** Arguments for {@link PluginPresentationPlacedViewsApi.rotateShape}. */
 export const PluginPresentationPlacedViewsRotateShapeArgs = z.object({
@@ -1124,25 +1188,24 @@ export type PluginPresentationPlacedViewsRotateShapeArgs = z.infer<
 export const PluginPlacedViewsDeleteShapesArgs = z.object({
   shapeIds: z.array(z.string().min(1)).min(1).max(500),
 })
-export type PluginPlacedViewsDeleteShapesArgs = z.infer<typeof PluginPlacedViewsDeleteShapesArgs>
+export type PluginPlacedViewsDeleteShapesArgs = z.infer<
+  typeof PluginPlacedViewsDeleteShapesArgs
+>
 
 /** Arguments for {@link PluginPresentationPlacedViewsApi.setOpacity}. */
 export const PluginPlacedViewsSetOpacityArgs = z.object({
   shapeId: z.string().min(1),
   opacity: z.number().finite().min(0).max(1),
 })
-export type PluginPlacedViewsSetOpacityArgs = z.infer<typeof PluginPlacedViewsSetOpacityArgs>
+export type PluginPlacedViewsSetOpacityArgs = z.infer<
+  typeof PluginPlacedViewsSetOpacityArgs
+>
 
 /** Arguments for {@link PluginPresentationPlacedViewsApi.setMask}. */
 export const PluginPlacedViewsSetMaskArgs = z.object({
   shapeId: z.string().min(1),
   enabled: z.boolean(),
 })
-export type PluginPlacedViewsSetMaskArgs = z.infer<typeof PluginPlacedViewsSetMaskArgs>
-
-/** Arguments for {@link PluginPresentationPlacedViewsApi.setLod}. */
-export const PluginPlacedViewsSetLodArgs = z.object({
-  shapeId: z.string().min(1),
-  lod: PluginViewLod,
-})
-export type PluginPlacedViewsSetLodArgs = z.infer<typeof PluginPlacedViewsSetLodArgs>
+export type PluginPlacedViewsSetMaskArgs = z.infer<
+  typeof PluginPlacedViewsSetMaskArgs
+>