@snaptrude/plugin-core 0.7.1 → 0.9.0

package/src/api/presentation/sheets.ts

@@ -8,8 +8,11 @@ import { PluginApiReturn } from "../../types"
  * These methods require **Present mode to be open** (the documentation editor) —
  * reads return `[]`/`null` and writes throw when it is not.
  *
- * `list`/`get` are reads; `create` adds a sheet and `place` drops a saved view
- * onto a sheet (returning the id of the created canvas shape).
+ * `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.
  *
  * Accessed via `snaptrude.presentation.sheets`.
  */
@@ -56,56 +59,278 @@ export abstract class PluginPresentationSheetsApi {
   /**
    * Create a new layout sheet.
    *
+   * Optionally sets the paper size and orientation — the same presets as the
+   * sheet header's size dropdown (ANSI A–E, Arch A–E1, ISO A4–A0). When `size`
+   * is omitted the sheet inherits the editor session's last-used size
+   * (initially ANSI B) in landscape, so pass `size` explicitly whenever the
+   * output format matters.
+   *
    * Requires Present mode to be open.
    *
    * @param name - Display name for the new sheet (optional).
+   * @param options - Optional `size` ({@linkcode PluginSheetSize} paper preset)
+   *   and `orientation` ({@linkcode PluginSheetOrientation}; `"landscape"` when
+   *   omitted).
    * @returns The newly created {@linkcode PluginPresentationSheet}.
    * @throws If Present mode is not open.
    *
    * @examplePrompt Create a new sheet called Cover
-   * @examplePrompt Add a layout sheet
-   * @examplePrompt Make a new presentation sheet named Floor Plans
+   * @examplePrompt Add an A3 landscape layout sheet
+   * @examplePrompt Make a new ANSI D presentation sheet named Floor Plans
+   * @examplePrompt Create a portrait A4 sheet
    *
    * # Example
    * ```ts
-   * const sheet = await snaptrude.presentation.sheets.create("Cover")
+   * const sheet = await snaptrude.presentation.sheets.create("Cover", {
+   *   size: "ISO_A3",
+   *   orientation: "landscape",
+   * })
    * ```
    */
   public abstract create(
     name?: string,
+    options?: { size?: PluginSheetSize; orientation?: PluginSheetOrientation },
+  ): PluginApiReturn<PluginPresentationSheet>
+
+  /**
+   * Set a sheet's paper size and/or orientation.
+   *
+   * Applies one of the standard paper presets — exactly what the sheet header's
+   * size dropdown and orientation toggle do. Content that no longer fits inside
+   * the resized sheet is moved out onto the canvas (matching the native
+   * behavior). Undoable. Does not change the user's remembered default size for
+   * new sheets.
+   *
+   * Requires Present mode to be open.
+   *
+   * @param sheetId - The id of the sheet to resize.
+   * @param size - The paper preset ({@linkcode PluginSheetSize}).
+   * @param orientation - Optional {@linkcode PluginSheetOrientation}; keeps the
+   *   sheet's current orientation when omitted.
+   * @returns The updated {@linkcode PluginPresentationSheet}.
+   * @throws If Present mode is not open, or the sheet id is invalid.
+   *
+   * @examplePrompt Resize sheet_1 to A1
+   * @examplePrompt Make the cover sheet ANSI B portrait
+   * @examplePrompt Change this sheet to Arch D landscape
+   * @examplePrompt Set the sheet size to A3
+   *
+   * # Example
+   * ```ts
+   * const sheet = await snaptrude.presentation.sheets.setSize("sheet_1", "ISO_A1", "portrait")
+   * ```
+   */
+  public abstract setSize(
+    sheetId: string,
+    size: PluginSheetSize,
+    orientation?: PluginSheetOrientation,
   ): PluginApiReturn<PluginPresentationSheet>
 
   /**
    * Place a saved view onto a sheet.
    *
-   * Drops the given view onto the sheet at an optional position and returns the
-   * id of the created canvas shape. Requires Present mode to be open.
+   * 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.
    *
    * @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 (a default is used when omitted).
+   *   where to place it (sheet centre when omitted) — and `scale` — a standard
+   *   scale value for the project's unit system (2D/site-plan views only;
+   *   auto-fit when omitted).
    * @returns A {@linkcode PluginPresentationSheetsPlaceResult} with the created
    *   `shapeId`.
-   * @throws If Present mode is not open, or the sheet/view id is invalid.
+   * @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.
    *
    * @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
+   * @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
    *
    * # Example
    * ```ts
-   * const { shapeId } = await snaptrude.presentation.sheets.place("sheet_1", "view_123")
+   * const { shapeId } = await snaptrude.presentation.sheets.place("sheet_1", "view_123", {
+   *   scale: 100, // 1:100 (metric project)
+   * })
    * ```
    */
   public abstract place(
     sheetId: string,
     viewId: string,
-    options?: { position?: PluginSheetPosition },
+    options?: { position?: PluginSheetPosition; scale?: number },
   ): PluginApiReturn<PluginPresentationSheetsPlaceResult>
+
+  /**
+   * Rename a layout sheet.
+   *
+   * Sets the sheet's display name — the same label the sheets panel shows and
+   * that `list`/`get` read back. Requires Present mode to be open.
+   *
+   * @param sheetId - The id of the sheet to rename.
+   * @param name - The new display name (non-empty after trimming).
+   * @returns The updated {@linkcode PluginPresentationSheet}.
+   * @throws If Present mode is not open, or the sheet id is invalid.
+   *
+   * @examplePrompt Rename sheet_1 to Cover
+   * @examplePrompt Call the first sheet Ground Floor
+   * @examplePrompt Change this sheet's name to Site Plan
+   *
+   * # Example
+   * ```ts
+   * const sheet = await snaptrude.presentation.sheets.rename("sheet_1", "Cover")
+   * ```
+   */
+  public abstract rename(
+    sheetId: string,
+    name: string,
+  ): PluginApiReturn<PluginPresentationSheet>
+
+  /**
+   * Delete a layout sheet.
+   *
+   * Removes the sheet (and its placed content) from the presentation and
+   * renumbers the remaining sheets. Requires Present mode to be open. Auto-diagram
+   * sheets cannot be deleted through the API — remove those from the Present UI.
+   *
+   * @param sheetId - The id of the sheet to delete.
+   * @returns The id of the deleted sheet
+   *   (a {@linkcode PluginPresentationSheetsDeleteResult}).
+   * @throws If Present mode is not open, the sheet id is invalid, or the sheet is
+   *   an auto-diagram sheet.
+   *
+   * @examplePrompt Delete sheet_2
+   * @examplePrompt Remove the Cover sheet
+   * @examplePrompt Get rid of the last layout sheet
+   *
+   * # Example
+   * ```ts
+   * const { id } = await snaptrude.presentation.sheets.delete("sheet_2")
+   * ```
+   */
+  public abstract delete(
+    sheetId: string,
+  ): PluginApiReturn<PluginPresentationSheetsDeleteResult>
+
+  /**
+   * Move a sheet to a new position in the sheet order.
+   *
+   * Reorders the sheet to the given zero-based `index` (as the sheets panel does
+   * when a sheet is dragged) and renumbers the rest. `index` is clamped to the
+   * valid range. Requires Present mode to be open.
+   *
+   * @param sheetId - The id of the sheet to move.
+   * @param index - Zero-based target position in the sheet order.
+   * @returns The sheets in their new order
+   *   (a {@linkcode PluginPresentationSheetsListResult}).
+   * @throws If Present mode is not open, or the sheet id is invalid.
+   *
+   * @examplePrompt Move sheet_3 to the front
+   * @examplePrompt Make the Cover sheet the first sheet
+   * @examplePrompt Reorder this sheet to position 2
+   *
+   * # Example
+   * ```ts
+   * const { sheets } = await snaptrude.presentation.sheets.reorder("sheet_3", 0)
+   * ```
+   */
+  public abstract reorder(
+    sheetId: string,
+    index: number,
+  ): PluginApiReturn<PluginPresentationSheetsListResult>
+
+  /**
+   * Make a sheet the active sheet.
+   *
+   * Selects the sheet in the sheets panel and navigates the Present canvas to it
+   * (the same as clicking it in the panel). Requires Present mode to be open.
+   *
+   * @param sheetId - The id of the sheet to activate.
+   * @returns The now-active {@linkcode PluginPresentationSheet}.
+   * @throws If Present mode is not open, or the sheet id is invalid.
+   *
+   * @examplePrompt Go to sheet_1
+   * @examplePrompt Open the Cover sheet
+   * @examplePrompt Switch to the Site Plan sheet
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.sheets.setActive("sheet_1")
+   * ```
+   */
+  public abstract setActive(
+    sheetId: string,
+  ): PluginApiReturn<PluginPresentationSheet>
+
+  /**
+   * Refresh placed views to the current model state.
+   *
+   * Re-renders the presentation's placed **views** — the live linked view shapes —
+   * from the current model (the "Update views" action). Views placed with
+   * {@linkcode PluginPresentationSheetsApi.place} are live view shapes too, so
+   * they refresh along with panel-dropped ones. Pass `sheetId` to refresh only
+   * the views on that sheet, or omit it to refresh every placed view. Requires
+   * Present mode to be open.
+   *
+   * @param options - Optional `sheetId` — restrict the refresh to one sheet's
+   *   placed views (all placed views when omitted).
+   * @returns The ids of the placed view shapes submitted for refresh
+   *   (a {@linkcode PluginPresentationSheetsUpdatePlacedViewResult}).
+   * @throws If Present mode is not open, or `sheetId` is given but invalid.
+   *
+   * @examplePrompt Update all the placed views to the latest model
+   * @examplePrompt Refresh the views on sheet_1
+   * @examplePrompt Re-render the placed views after my edits
+   *
+   * # Example
+   * ```ts
+   * const { shapeIds } = await snaptrude.presentation.sheets.updatePlacedView()
+   * ```
+   */
+  public abstract updatePlacedView(options?: {
+    sheetId?: string
+  }): PluginApiReturn<PluginPresentationSheetsUpdatePlacedViewResult>
 }
 
+/**
+ * Standard paper-size presets for layout sheets — identical to the sheet
+ * header's size dropdown in Present mode.
+ */
+export const PluginSheetSize = z.enum([
+  "ANSI_A",
+  "ANSI_B",
+  "ANSI_C",
+  "ANSI_D",
+  "ANSI_E",
+  "ARCH_A",
+  "ARCH_B",
+  "ARCH_C",
+  "ARCH_D",
+  "ARCH_E",
+  "ARCH_E1",
+  "ISO_A4",
+  "ISO_A3",
+  "ISO_A2",
+  "ISO_A1",
+  "ISO_A0",
+])
+export type PluginSheetSize = z.infer<typeof PluginSheetSize>
+
+/** Sheet orientation. */
+export const PluginSheetOrientation = z.enum(["landscape", "portrait"])
+export type PluginSheetOrientation = z.infer<typeof PluginSheetOrientation>
+
 /**
  * A layout sheet in the presentation.
  *
@@ -113,10 +338,14 @@ export abstract class PluginPresentationSheetsApi {
  * |---|---|---|
  * | `id` | `string` | Unique sheet id |
  * | `name` | `string` | Display name |
+ * | `size` | {@linkcode PluginSheetSize}` \| null` | Paper preset (`null` for a legacy sheet without one) |
+ * | `orientation` | {@linkcode PluginSheetOrientation}` \| null` | Orientation (`null` for a legacy sheet) |
  */
 export const PluginPresentationSheet = z.object({
   id: z.string(),
   name: z.string(),
+  size: PluginSheetSize.nullable(),
+  orientation: PluginSheetOrientation.nullable(),
 })
 export type PluginPresentationSheet = z.infer<typeof PluginPresentationSheet>
 
@@ -160,11 +389,23 @@ export type PluginPresentationSheetsGetResult = z.infer<
 /** Arguments for {@linkcode PluginPresentationSheetsApi.create}. */
 export const PluginPresentationSheetsCreateArgs = z.object({
   name: z.string().optional(),
+  size: PluginSheetSize.optional(),
+  orientation: PluginSheetOrientation.optional(),
 })
 export type PluginPresentationSheetsCreateArgs = z.infer<
   typeof PluginPresentationSheetsCreateArgs
 >
 
+/** Arguments for {@linkcode PluginPresentationSheetsApi.setSize}. */
+export const PluginPresentationSheetsSetSizeArgs = z.object({
+  sheetId: z.string(),
+  size: PluginSheetSize,
+  orientation: PluginSheetOrientation.optional(),
+})
+export type PluginPresentationSheetsSetSizeArgs = z.infer<
+  typeof PluginPresentationSheetsSetSizeArgs
+>
+
 /**
  * Arguments for {@linkcode PluginPresentationSheetsApi.place}.
  *
@@ -172,12 +413,14 @@ export type PluginPresentationSheetsCreateArgs = z.infer<
  * |---|---|---|
  * | `sheetId` | `string` | The sheet to place onto |
  * | `viewId` | `string` | The saved view to place |
- * | `position` | {@linkcode PluginSheetPosition}` \| undefined` | Where to place it (a default is used when omitted) |
+ * | `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) |
  */
 export const PluginPresentationSheetsPlaceArgs = z.object({
   sheetId: z.string(),
   viewId: z.string(),
   position: PluginSheetPosition.optional(),
+  scale: z.number().positive().optional(),
 })
 export type PluginPresentationSheetsPlaceArgs = z.infer<
   typeof PluginPresentationSheetsPlaceArgs
@@ -196,3 +439,93 @@ export const PluginPresentationSheetsPlaceResult = z.object({
 export type PluginPresentationSheetsPlaceResult = z.infer<
   typeof PluginPresentationSheetsPlaceResult
 >
+
+/**
+ * Arguments for {@linkcode PluginPresentationSheetsApi.rename}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetId` | `string` | The sheet to rename |
+ * | `name` | `string` | New display name (non-empty after trimming) |
+ */
+export const PluginPresentationSheetsRenameArgs = z.object({
+  sheetId: z.string(),
+  name: z.string().trim().min(1),
+})
+export type PluginPresentationSheetsRenameArgs = z.infer<
+  typeof PluginPresentationSheetsRenameArgs
+>
+
+/** Arguments for {@linkcode PluginPresentationSheetsApi.delete}. */
+export const PluginPresentationSheetsDeleteArgs = z.object({
+  sheetId: z.string(),
+})
+export type PluginPresentationSheetsDeleteArgs = z.infer<
+  typeof PluginPresentationSheetsDeleteArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationSheetsApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Id of the deleted sheet |
+ */
+export const PluginPresentationSheetsDeleteResult = z.object({
+  id: z.string(),
+})
+export type PluginPresentationSheetsDeleteResult = z.infer<
+  typeof PluginPresentationSheetsDeleteResult
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationSheetsApi.reorder}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetId` | `string` | The sheet to move |
+ * | `index` | `number` | Zero-based target position (clamped to range) |
+ */
+export const PluginPresentationSheetsReorderArgs = z.object({
+  sheetId: z.string(),
+  index: z.number().int().min(0),
+})
+export type PluginPresentationSheetsReorderArgs = z.infer<
+  typeof PluginPresentationSheetsReorderArgs
+>
+
+/** Arguments for {@linkcode PluginPresentationSheetsApi.setActive}. */
+export const PluginPresentationSheetsSetActiveArgs = z.object({
+  sheetId: z.string(),
+})
+export type PluginPresentationSheetsSetActiveArgs = z.infer<
+  typeof PluginPresentationSheetsSetActiveArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationSheetsApi.updatePlacedView}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetId` | `string`? | Restrict the refresh to one sheet's placed views |
+ */
+export const PluginPresentationSheetsUpdatePlacedViewArgs = z.object({
+  sheetId: z.string().optional(),
+})
+export type PluginPresentationSheetsUpdatePlacedViewArgs = z.infer<
+  typeof PluginPresentationSheetsUpdatePlacedViewArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationSheetsApi.updatePlacedView}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeIds` | `string[]` | Ids of the placed view shapes submitted for refresh |
+ */
+export const PluginPresentationSheetsUpdatePlacedViewResult = z.object({
+  shapeIds: z.array(z.string()),
+})
+export type PluginPresentationSheetsUpdatePlacedViewResult = z.infer<
+  typeof PluginPresentationSheetsUpdatePlacedViewResult
+>