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

package/src/api/presentation/views.ts

@@ -2,7 +2,7 @@ import * as z from "zod"
 import { PluginApiReturn } from "../../types"
 
 /**
- * Presentation views — read the saved 2D/3D views used to prepare presentations.
+ * Presentation views — read the saved plan, 3D, and elevation views used to prepare presentations.
  *
  * A **view** is a saved camera/plan: a sheet-ready 2D plan or a saved 3D view.
  * A plugin can list and read views, capture them to images, activate one (move
@@ -24,10 +24,10 @@ export abstract class PluginPresentationViewsApi {
    * List the saved views in the active project.
    *
    * @returns A {@linkcode PluginPresentationViewsListResult} with a `views` array
-   *   of 2D and 3D views (empty when the project has none).
+   *   of plan, 3D, and elevation views (empty when the project has none).
    *
    * @examplePrompt List all the saved views
-   * @examplePrompt What 2D and 3D views are in this project?
+   * @examplePrompt What plan, 3D, and elevation views are in this project?
    * @examplePrompt Which view is currently active?
    * @examplePrompt Get the names of every presentation view
    * @examplePrompt Show me the 3D views I can put on a sheet
@@ -83,7 +83,9 @@ export abstract class PluginPresentationViewsApi {
    *
    * Captures the **current** viewport by default; pass `viewId` to capture a
    * specific saved view (which briefly applies that view to the scene). Use
-   * `format`/`resolution` to control the output.
+   * `format`/`resolution` to control the output. This shoots the Design (3D)
+   * canvas; to screenshot the Present canvas use
+   * {@linkcode PluginPresentationCameraApi.capture}.
    *
    * @param options - All optional: `viewId` (capture this saved view; omit for the
    *   current viewport), `format` (default `"png"`), `resolution` (e.g. `"1280x720"`).
@@ -113,6 +115,10 @@ export abstract class PluginPresentationViewsApi {
    * Applies the view's camera, visibility, and storey state to the live scene.
    * Paired with {@linkcode PluginPresentationViewsApi.getActive}.
    *
+   * While Present is open this sets the Design frame a view saved in Present
+   * is taken from; it never moves the Present sheet canvas; use
+   * `presentation.camera` for that.
+   *
    * @param viewId - The id of the view to activate.
    * @returns The id of the now-active view.
    * @throws If no view has the given id.
@@ -136,6 +142,15 @@ export abstract class PluginPresentationViewsApi {
    *
    * Creates a camera bookmark (not geometry) from where the camera is now.
    *
+   * Works while Present mode is open. Present draws its drawings on the same
+   * 3D scene, so a view saved in Present takes its framing (camera, 2D or 3D
+   * mode, projection, storey, building) from the Design frame instead: the one
+   * the user had when Present opened, or one a plugin set since with
+   * `setActive`, `updateSettings({ viewMode })`, `core.camera`, `core.zoom`,
+   * `core.storeys.setActive`, `core.storeys.layers.setActive` or
+   * `core.buildings.setActive`. It never moves the Present sheet canvas; use
+   * `presentation.camera` for that.
+   *
    * @param name - Name for the new view (a default is used when omitted).
    * @param options - Optional `kind` (what kind of view to save, default
    *   `"view"`) and `storey` (save the view on a specific storey — the storey is
@@ -169,12 +184,16 @@ export abstract class PluginPresentationViewsApi {
    *
    * @param viewId - The id of the view to read settings for.
    * @returns The view's {@linkcode PluginPresentationViewSettings}, or `null` if
-   *   no view has that id.
+   *   no view has that id. A plan view also reports its `cutPlaneHeight`,
+   *   `viewDepthStorey` and `showOverheadObjects` (saved values, or the product
+   *   defaults for a plan saved before cut ranges existed); other views omit them.
    *
    * @examplePrompt What color mode is the Ground Floor view using?
    * @examplePrompt Get the display settings for this view
    * @examplePrompt Does the site plan view show axes and labels?
    * @examplePrompt Read the background color of the active view
+   * @examplePrompt What is the cut height of this plan?
+   * @examplePrompt How deep does this plan look below the cut?
    *
    * # Example
    * ```ts
@@ -224,14 +243,24 @@ export abstract class PluginPresentationViewsApi {
    * toggle the view-settings modal runs); on other views the mode is applied
    * the next time the view is activated.
    *
+   * `cutPlaneHeight`, `viewDepthStorey` and `showOverheadObjects` set the plan's
+   * cut range and apply to **plan views only** (patching them on a 3D, elevation
+   * or site-plan view is rejected). `cutPlaneHeight` is in engine units, the same
+   * unit as `story.height`, and must be greater than 0 and less than the plan
+   * storey's height. `viewDepthStorey` must be an existing storey at or below the
+   * plan's storey. A sparse patch leaves the other two range fields as they
+   * were; on the active plan the canvas redraws live.
+   *
    * @param viewId - The id of the view to update.
    * @param settings - A partial {@linkcode PluginPresentationViewSettings}; any
    *   omitted field is left unchanged.
    * @returns The updated view's `id`.
    * @throws If writes are disabled, no view has the given id, the patch is
    *   contradictory (`showLabels: false` with a non-empty `labels`, or
-   *   `showLabels: true` with an explicitly empty `labels` list), or
-   *   `viewMode: "perspective"` is patched on a 2D plan view.
+   *   `showLabels: true` with an explicitly empty `labels` list),
+   *   `viewMode: "perspective"` is patched on a 2D plan view, a plan-range
+   *   field is patched on a view that is not a plan, or the cut height / depth
+   *   is out of range.
    *
    * @examplePrompt Switch this view to monochrome color mode
    * @examplePrompt Turn off the axis in the Ground Floor view
@@ -239,6 +268,9 @@ export abstract class PluginPresentationViewsApi {
    * @examplePrompt Show area labels on this view
    * @examplePrompt Enable hidden-line mode for the section view
    * @examplePrompt Make the 3D view orthographic instead of perspective
+   * @examplePrompt Raise the cut plane of the Ground Floor plan to 1.8 m
+   * @examplePrompt Show the basement below in this plan
+   * @examplePrompt Hide the overhead objects in this plan
    *
    * # Example
    * ```ts
@@ -250,6 +282,12 @@ export abstract class PluginPresentationViewsApi {
    * await snaptrude.presentation.views.updateSettings("view_123", {
    *   viewMode: "isometric",
    * })
+   * // set a plan's range: cut 1.2 m up, show the basement below, no overhead
+   * await snaptrude.presentation.views.updateSettings("plan_1", {
+   *   cutPlaneHeight: 4.72,
+   *   viewDepthStorey: -1,
+   *   showOverheadObjects: false,
+   * })
    * ```
    */
   public abstract updateSettings(
@@ -313,13 +351,36 @@ export abstract class PluginPresentationViewsApi {
 }
 
 /**
- * The kind of a saved view: a 2D plan view or a 3D view.
+ * The rendering category of a saved view. Existing plan/3D values are preserved;
+ * elevations are identified independently of their orthographic 3D camera.
  */
-export const PluginPresentationViewType = z.enum(["2d", "3d"])
+export const PluginPresentationViewType = z.enum(["2d", "3d", "elevation"])
 export type PluginPresentationViewType = z.infer<
   typeof PluginPresentationViewType
 >
 
+/** The native semantic kind persisted for a saved view. */
+export const PluginPresentationViewKind = z.enum([
+  "plan",
+  "sitePlan",
+  "threeD",
+  "elevation",
+])
+export type PluginPresentationViewKind = z.infer<
+  typeof PluginPresentationViewKind
+>
+
+/** Cardinal direction for an elevation; non-elevation views return `null`. */
+export const PluginPresentationElevationDirection = z.enum([
+  "north",
+  "east",
+  "south",
+  "west",
+])
+export type PluginPresentationElevationDirection = z.infer<
+  typeof PluginPresentationElevationDirection
+>
+
 /**
  * A saved presentation view.
  *
@@ -327,7 +388,9 @@ export type PluginPresentationViewType = z.infer<
  * |---|---|---|
  * | `id` | `string` | Unique view id |
  * | `name` | `string` | Display name |
- * | `type` | `"2d" \| "3d"` | Whether this is a 2D plan view or a 3D view |
+ * | `type` | `"2d" \| "3d" \| "elevation"` | Rendering category; elevations are distinct from ordinary 3D views |
+ * | `kind` | {@linkcode PluginPresentationViewKind} | Native semantic view kind |
+ * | `direction` | {@linkcode PluginPresentationElevationDirection}` \| null` | Cardinal direction for elevations; otherwise `null` |
  * | `isActive` | `boolean` | Whether this view is the currently active view |
  * | `storey` | `number \| null` | The storey this view was saved on (`null` on older views saved without one) |
  */
@@ -335,6 +398,8 @@ export const PluginPresentationView = z.object({
   id: z.string(),
   name: z.string(),
   type: PluginPresentationViewType,
+  kind: PluginPresentationViewKind,
+  direction: PluginPresentationElevationDirection.nullable(),
   isActive: z.boolean(),
   storey: z.number().nullable(),
 })
@@ -531,6 +596,9 @@ export type PluginPresentationViewMode = z.infer<
  * | `showEdges` | `boolean` | Whether edges are shown; `false` = hidden-line rendering |
  * | `showLabels` | `boolean` | Master label switch — whether on-canvas labels are shown at all. `true` always pairs with a non-empty `labels` selection (labels render only while the selection is non-empty; there is no labels-on-with-empty-selection state) |
  * | `labels` | {@linkcode PluginPresentationViewLabel}`[]` | Which label categories are selected. When `showLabels` is `false` the view stores no selection and this reads `[]` |
+ * | `cutPlaneHeight` | `number`? | **Plan views only.** Height of the plan's cut plane above its storey base, in engine units (the unit `story.height` uses). Absent on 3D and elevation views |
+ * | `viewDepthStorey` | `number`? | **Plan views only.** The lowest storey the plan shows below the cut; defaults to the plan's own storey. Absent on 3D and elevation views |
+ * | `showOverheadObjects` | `boolean`? | **Plan views only.** Whether objects above the cut are drawn as dashed overhead linework. Absent on 3D and elevation views |
  */
 export const PluginPresentationViewSettings = z.object({
   backgroundColor: z.string(),
@@ -540,6 +608,9 @@ export const PluginPresentationViewSettings = z.object({
   showEdges: z.boolean(),
   showLabels: z.boolean(),
   labels: z.array(PluginPresentationViewLabel),
+  cutPlaneHeight: z.number().finite().positive().optional(),
+  viewDepthStorey: z.number().int().optional(),
+  showOverheadObjects: z.boolean().optional(),
 })
 export type PluginPresentationViewSettings = z.infer<
   typeof PluginPresentationViewSettings