@snaptrude/plugin-core 0.0.0-dev-20260708130115 → 0.0.0-dev-20260827135706

package/src/api/presentation/tables.ts

@@ -0,0 +1,84 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import type { PluginCanvasShape } from "./placedViews"
+
+/**
+ * Presentation tables — place data tables on Present-mode sheets.
+ *
+ * The scriptable counterpart of the Present canvas's table paste (the flow
+ * that turns a Program-mode / Google Sheets / Excel paste into a table
+ * shape): {@linkcode PluginPresentationTablesApi.place} takes plain string
+ * rows and creates one table shape on a sheet. Requires Present mode to be
+ * open.
+ *
+ * Accessed via `snaptrude.presentation.tables`.
+ */
+export abstract class PluginPresentationTablesApi {
+  constructor() {}
+
+  /**
+   * Place a table on a sheet.
+   *
+   * Creates one table shape from `table.rows` — the same shape the Present
+   * canvas creates when a spreadsheet table is pasted — and returns the
+   * created shape as a canvas-shape record. Cells are plain strings; rows may
+   * be ragged (each row needs at least one cell), capped at 10000 cells
+   * total. `options.position` is sheet-local (relative to the sheet's
+   * top-left, in canvas units — the same convention as `annotate.*`); when
+   * omitted the table lands where the paste flow would auto-place it (the
+   * center of the current viewport). One undo step. Requires Present mode to
+   * be open.
+   *
+   * @param sheetId - The sheet to place the table on.
+   * @param table - The table content: `rows`, an array of string-cell rows.
+   * @param options - Optional `position` (`{ x, y }`, relative to the sheet's
+   *   top-left — defaults to the paste flow's auto-placement).
+   * @returns The created table shape as a {@linkcode PluginCanvasShape}.
+   * @throws If Present mode is not open, the sheet id is invalid, or the
+   *   table is empty / exceeds the 10000-cell cap.
+   *
+   * @examplePrompt Put the area schedule as a table on Sheet 1
+   * @examplePrompt Add a table of the room programs to the cover sheet
+   * @examplePrompt Paste this data as a table on the sheet
+   * @examplePrompt Place a two-column table of space names and areas
+   *
+   * # Example
+   * ```ts
+   * const shape = await snaptrude.presentation.tables.place("sheet_1", {
+   *   rows: [
+   *     ["Room", "Area"],
+   *     ["Kitchen", "12.4 m²"],
+   *     ["Living", "28.0 m²"],
+   *   ],
+   * }, { position: { x: 40, y: 40 } })
+   * ```
+   */
+  public abstract place(
+    sheetId: string,
+    table: { rows: string[][] },
+    options?: { position?: { x: number; y: number } },
+  ): PluginApiReturn<PluginCanvasShape>
+}
+
+/**
+ * Arguments for {@linkcode PluginPresentationTablesApi.place}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `sheetId` | `string` | The sheet to place the table on |
+ * | `rows` | `string[][]` | Table cells as string rows (non-empty; ≤ 10000 cells total) |
+ * | `position` | `{ x: number; y: number } \| undefined` | Sheet-local position (default: paste auto-placement) |
+ */
+export const PluginPresentationTablesPlaceArgs = z.object({
+  sheetId: z.string().min(1),
+  rows: z
+    .array(z.array(z.string()).min(1))
+    .min(1)
+    .refine((rows) => rows.reduce((n, r) => n + r.length, 0) <= 10000, {
+      message: "table exceeds the 10000-cell cap",
+    }),
+  position: z.object({ x: z.number(), y: z.number() }).optional(),
+})
+export type PluginPresentationTablesPlaceArgs = z.infer<
+  typeof PluginPresentationTablesPlaceArgs
+>

package/src/api/presentation/views.ts

@@ -6,12 +6,14 @@ import { PluginApiReturn } from "../../types"
  *
  * 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
- * the camera to it), and save the current camera as a new view.
+ * the camera to it), save the current camera as a new view, rename or delete a
+ * saved view, and read/update a view's display settings (background, color
+ * mode, view mode, axis, edges, labels). Each view carries the `storey` it was
+ * saved on.
  *
- * `list`/`get`/`getActive`/`capture` are reads; `setActive`/`create` are writes
- * (a view is a camera bookmark — not geometry). Members typed optional (`?`) are
- * authored ahead of the host: declared for plugins/codegen but not yet on the
- * live discovery surface until the host lands them.
+ * `list`/`get`/`getActive`/`capture`/`getSettings` are reads;
+ * `setActive`/`create`/`rename`/`delete`/`updateSettings` are writes (a view is
+ * a camera bookmark — not geometry).
  *
  * Accessed via `snaptrude.presentation.views`.
  */
@@ -135,24 +137,179 @@ export abstract class PluginPresentationViewsApi {
    * Creates a camera bookmark (not geometry) from where the camera is now.
    *
    * @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"`).
+   * @param options - Optional `kind` (what kind of view to save, default
+   *   `"view"`) and `storey` (save the view on a specific storey — the storey is
+   *   activated first, matching the storey the view is captured on; when omitted
+   *   the current active storey is used).
    * @returns The newly created {@linkcode PluginPresentationView}.
-   * @throws If the view could not be saved.
+   * @throws If `storey` is given but no such storey exists, or the view could
+   *   not be saved.
    *
    * @examplePrompt Save the current view as Lobby Perspective
    * @examplePrompt Create a new saved view from where I'm looking
    * @examplePrompt Bookmark this camera angle
    * @examplePrompt Save the current 2D plan as a view
+   * @examplePrompt Save a view on the second storey
    *
    * # Example
    * ```ts
    * const view = await snaptrude.presentation.views.create("Lobby")
+   * // …or capture the view on a specific storey
+   * const level2 = await snaptrude.presentation.views.create("Level 2", { storey: 2 })
    * ```
    */
   public abstract create(
     name?: string,
-    options?: { kind?: "view" | "sitePlan" },
+    options?: { kind?: "view" | "sitePlan"; storey?: number },
   ): PluginApiReturn<PluginPresentationViewsCreateResult>
+
+  /**
+   * Read a saved view's display settings (background, color mode, view mode,
+   * axis, edges, labels).
+   *
+   * @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.
+   *
+   * @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
+   *
+   * # Example
+   * ```ts
+   * const settings = await snaptrude.presentation.views.getSettings("view_123")
+   * if (settings) console.log(settings.colorMode, settings.backgroundColor)
+   * ```
+   */
+  public abstract getSettings(
+    viewId: string,
+  ): PluginApiReturn<PluginPresentationViewsGetSettingsResult>
+
+  /**
+   * Update a saved view's display settings (partial patch — only the fields you
+   * pass change).
+   *
+   * Persists and broadcasts the change; if the view is currently active, the
+   * scene updates live. **Not Ctrl+Z-undoable** — view-metadata edits publish
+   * directly and do not land on the local undo stack; this matches how the
+   * product's own view-settings UI behaves.
+   *
+   * Label patch semantics (mirroring the product, which stores no label
+   * selection while labels are off):
+   *
+   * - `{ showLabels: true }` alone turns labels on; if the view has no stored
+   *   selection, the product defaults (`objectLabels`, `areas`) are applied —
+   *   labels are never "on" with an empty selection (the product has no such
+   *   state; labels render only while the selection is non-empty).
+   * - `{ labels: [...] }` alone sets the selection **and turns labels on**.
+   * - `{ showLabels: false }` turns labels off and **clears the stored
+   *   selection** — a later read returns `labels: []`.
+   * - `{ showLabels: false, labels: [...] }` with a non-empty list is
+   *   contradictory and **rejected** (nothing is silently discarded).
+   * - `{ showLabels: true, labels: [] }` is likewise contradictory and
+   *   **rejected** — pass a non-empty list, or omit `labels` to get the
+   *   defaults.
+   *
+   * `colorMode` accepts the `tag:<categoryId>` scheme strings returned by
+   * {@linkcode PluginPresentationViewsApi.getSettings}, so read-then-write
+   * round-trips a tag-based color scheme unchanged.
+   *
+   * `viewMode` (`"perspective"` | `"isometric"`) applies to **3D views only** —
+   * a 2D plan is always orthographic, so a `viewMode: "perspective"` patch on a
+   * 2D view is rejected. `"isometric"` on a 2D plan is accepted as a no-op (the
+   * plan is already orthographic), so writing back exactly what
+   * {@linkcode PluginPresentationViewsApi.getSettings} returned is always a
+   * no-op. On the active view the camera switches projection live (the same
+   * toggle the view-settings modal runs); on other views the mode is applied
+   * the next time the view is activated.
+   *
+   * @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.
+   *
+   * @examplePrompt Switch this view to monochrome color mode
+   * @examplePrompt Turn off the axis in the Ground Floor view
+   * @examplePrompt Set the background of the active view to white
+   * @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
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.presentation.views.updateSettings("view_123", {
+   *   colorMode: "monochrome",
+   *   showAxis: false,
+   * })
+   * // switch a 3D view to an isometric (orthographic) projection
+   * await snaptrude.presentation.views.updateSettings("view_123", {
+   *   viewMode: "isometric",
+   * })
+   * ```
+   */
+  public abstract updateSettings(
+    viewId: string,
+    settings: Partial<PluginPresentationViewSettings>,
+  ): PluginApiReturn<PluginPresentationViewsUpdateSettingsResult>
+
+  /**
+   * Rename a saved view.
+   *
+   * Sets the view's display name — the same label the views panel shows and
+   * that `list`/`get` read back. Names must be unique within the proposal and
+   * cannot contain the characters `\ : { } [ ] | ; < > ? ~`.
+   *
+   * @param viewId - The id of the view to rename.
+   * @param name - The new display name (non-empty after trimming).
+   * @returns The updated {@linkcode PluginPresentationView}.
+   * @throws If writes are disabled, no view has the given id, the name is
+   *   empty/invalid, or another view in the proposal already has that name.
+   *
+   * @examplePrompt Rename the view Lobby to Entrance Lobby
+   * @examplePrompt Call this view Ground Floor Plan
+   * @examplePrompt Change the active view's name to Final
+   *
+   * # Example
+   * ```ts
+   * const view = await snaptrude.presentation.views.rename("view_123", "Entrance")
+   * ```
+   */
+  public abstract rename(
+    viewId: string,
+    name: string,
+  ): PluginApiReturn<PluginPresentationViewsRenameResult>
+
+  /**
+   * Delete a saved view.
+   *
+   * Removes the view from the project and the views panel (the panel's own
+   * delete action). If the deleted view was active, the product falls back to
+   * the default plan/3D view. Default views (the built-in plan/3D/site-plan
+   * entries) cannot be deleted.
+   *
+   * @param viewId - The id of the view to delete.
+   * @returns The id of the deleted view
+   *   (a {@linkcode PluginPresentationViewsDeleteResult}).
+   * @throws If writes are disabled, no view has the given id, or the view is a
+   *   default view.
+   *
+   * @examplePrompt Delete the view named Old Draft
+   * @examplePrompt Remove this saved view
+   * @examplePrompt Get rid of the Lobby camera bookmark
+   *
+   * # Example
+   * ```ts
+   * const { id } = await snaptrude.presentation.views.delete("view_123")
+   * ```
+   */
+  public abstract delete(
+    viewId: string,
+  ): PluginApiReturn<PluginPresentationViewsDeleteResult>
 }
 
 /**
@@ -172,12 +329,14 @@ export type PluginPresentationViewType = z.infer<
  * | `name` | `string` | Display name |
  * | `type` | `"2d" \| "3d"` | Whether this is a 2D plan view or a 3D view |
  * | `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) |
  */
 export const PluginPresentationView = z.object({
   id: z.string(),
   name: z.string(),
   type: PluginPresentationViewType,
   isActive: z.boolean(),
+  storey: z.number().nullable(),
 })
 export type PluginPresentationView = z.infer<typeof PluginPresentationView>
 
@@ -287,10 +446,12 @@ export type PluginPresentationViewsSetActiveResult = z.infer<
  * |---|---|---|
  * | `name` | `string \| undefined` | Name for the new view (a default is used when omitted) |
  * | `kind` | `"view" \| "sitePlan" \| undefined` | What kind of view to save (default `"view"`). `"plan"` is not offered — the host cannot create a plan view without a `planId` this API does not carry. |
+ * | `storey` | `number \| undefined` | Save the view on this storey (activated before capture); defaults to the current active storey |
  */
 export const PluginPresentationViewsCreateArgs = z.object({
   name: z.string().optional(),
   kind: z.enum(["view", "sitePlan"]).optional(),
+  storey: z.number().optional(),
 })
 export type PluginPresentationViewsCreateArgs = z.infer<
   typeof PluginPresentationViewsCreateArgs
@@ -301,3 +462,210 @@ export const PluginPresentationViewsCreateResult = PluginPresentationView
 export type PluginPresentationViewsCreateResult = z.infer<
   typeof PluginPresentationViewsCreateResult
 >
+
+/**
+ * How the scene is colored in a view.
+ *
+ * | Value | Meaning |
+ * |---|---|
+ * | `monochrome` | Flat single-tone shading |
+ * | `texture` | Material textures/colors |
+ * | `department` | Colored by department |
+ * | `tag:<categoryId>` | Colored by a project tag category (e.g. `tag:ZONE`) |
+ *
+ * The `tag:<categoryId>` form carries the product's tag-based color schemes
+ * losslessly — reading a view that uses one returns the `tag:` string as-is,
+ * and writing it back preserves the scheme (read-then-write is safe).
+ */
+export const PluginPresentationViewColorMode = z.union([
+  z.enum(["monochrome", "texture", "department"]),
+  z.templateLiteral(["tag:", z.string()]),
+])
+export type PluginPresentationViewColorMode = z.infer<
+  typeof PluginPresentationViewColorMode
+>
+
+/**
+ * A category of on-canvas labels a view can show.
+ *
+ * | Value | Meaning |
+ * |---|---|
+ * | `objectLabels` | Per-object name labels |
+ * | `areas` | Area/room labels |
+ * | `department` | Department labels |
+ */
+export const PluginPresentationViewLabel = z.enum([
+  "objectLabels",
+  "areas",
+  "department",
+])
+export type PluginPresentationViewLabel = z.infer<
+  typeof PluginPresentationViewLabel
+>
+
+/**
+ * A view's camera projection: perspective, or isometric (orthographic).
+ *
+ * | Value | Meaning |
+ * |---|---|
+ * | `perspective` | Perspective projection (vanishing points) |
+ * | `isometric` | Orthographic projection (no perspective distortion) |
+ *
+ * Applies to 3D views; a 2D plan view is always orthographic and reads
+ * `"isometric"`.
+ */
+export const PluginPresentationViewMode = z.enum(["perspective", "isometric"])
+export type PluginPresentationViewMode = z.infer<
+  typeof PluginPresentationViewMode
+>
+
+/**
+ * A view's display settings.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `backgroundColor` | `string` | Canvas background as a hex color (e.g. `#ffffff`) |
+ * | `colorMode` | {@linkcode PluginPresentationViewColorMode} | How the scene is colored (including `tag:<categoryId>` schemes) |
+ * | `viewMode` | {@linkcode PluginPresentationViewMode} | Camera projection — `"perspective"` or `"isometric"` (orthographic). Writable on 3D views only; a 2D plan always reads `"isometric"` and accepts only `"isometric"` (a no-op) |
+ * | `showAxis` | `boolean` | Whether the X/Y/Z axes are shown |
+ * | `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 `[]` |
+ */
+export const PluginPresentationViewSettings = z.object({
+  backgroundColor: z.string(),
+  colorMode: PluginPresentationViewColorMode,
+  viewMode: PluginPresentationViewMode,
+  showAxis: z.boolean(),
+  showEdges: z.boolean(),
+  showLabels: z.boolean(),
+  labels: z.array(PluginPresentationViewLabel),
+})
+export type PluginPresentationViewSettings = z.infer<
+  typeof PluginPresentationViewSettings
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationViewsApi.getSettings}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The id of the view to read settings for |
+ */
+export const PluginPresentationViewsGetSettingsArgs = z.object({
+  id: z.string(),
+})
+export type PluginPresentationViewsGetSettingsArgs = z.infer<
+  typeof PluginPresentationViewsGetSettingsArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationViewsApi.getSettings} — the settings,
+ * or `null` when no view has that id.
+ */
+export const PluginPresentationViewsGetSettingsResult =
+  PluginPresentationViewSettings.nullable()
+export type PluginPresentationViewsGetSettingsResult = z.infer<
+  typeof PluginPresentationViewsGetSettingsResult
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationViewsApi.updateSettings}. The
+ * `settings` patch is partial — any omitted field is left unchanged. A patch
+ * pairing `showLabels: false` with a non-empty `labels` list, or
+ * `showLabels: true` with an explicitly empty `labels` list, is rejected as
+ * contradictory (see the method JSDoc for the full label patch semantics).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The id of the view to update |
+ * | `settings` | `Partial<`{@linkcode PluginPresentationViewSettings}`>` | The fields to change |
+ */
+export const PluginPresentationViewsUpdateSettingsArgs = z
+  .object({
+    id: z.string(),
+    settings: PluginPresentationViewSettings.partial(),
+  })
+  .refine(
+    (v) =>
+      !(
+        v.settings.showLabels === false && (v.settings.labels?.length ?? 0) > 0
+      ),
+    {
+      message:
+        "Contradictory patch: labels cannot be set while showLabels is false",
+    },
+  )
+  .refine(
+    (v) =>
+      !(
+        v.settings.showLabels === true &&
+        v.settings.labels !== undefined &&
+        v.settings.labels.length === 0
+      ),
+    {
+      message:
+        "Contradictory patch: showLabels cannot be true with an explicitly empty labels list — pass a non-empty list, or omit labels to apply the defaults",
+    },
+  )
+export type PluginPresentationViewsUpdateSettingsArgs = z.infer<
+  typeof PluginPresentationViewsUpdateSettingsArgs
+>
+
+/** Result of {@linkcode PluginPresentationViewsApi.updateSettings} — the updated view's id. */
+export const PluginPresentationViewsUpdateSettingsResult = z.object({
+  id: z.string(),
+})
+export type PluginPresentationViewsUpdateSettingsResult = z.infer<
+  typeof PluginPresentationViewsUpdateSettingsResult
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationViewsApi.rename}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The id of the view to rename |
+ * | `name` | `string` | New display name (non-empty after trimming) |
+ */
+export const PluginPresentationViewsRenameArgs = z.object({
+  id: z.string(),
+  name: z.string().trim().min(1),
+})
+export type PluginPresentationViewsRenameArgs = z.infer<
+  typeof PluginPresentationViewsRenameArgs
+>
+
+/** Result of {@linkcode PluginPresentationViewsApi.rename} — the renamed view. */
+export const PluginPresentationViewsRenameResult = PluginPresentationView
+export type PluginPresentationViewsRenameResult = z.infer<
+  typeof PluginPresentationViewsRenameResult
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationViewsApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The id of the view to delete |
+ */
+export const PluginPresentationViewsDeleteArgs = z.object({
+  id: z.string(),
+})
+export type PluginPresentationViewsDeleteArgs = z.infer<
+  typeof PluginPresentationViewsDeleteArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationViewsApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Id of the deleted view |
+ */
+export const PluginPresentationViewsDeleteResult = z.object({
+  id: z.string(),
+})
+export type PluginPresentationViewsDeleteResult = z.infer<
+  typeof PluginPresentationViewsDeleteResult
+>