@snaptrude/plugin-core 0.7.1 → 0.9.0

package/src/api/presentation/shapes.ts

@@ -0,0 +1,274 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import {
+  PluginAnnotateFill,
+  PluginAnnotateGeoKind,
+  PluginAnnotateTextColor,
+  PluginAnnotateTextSize,
+} from "./annotate"
+
+/**
+ * Presentation shapes — a stable, plugin-owned shape lifecycle on Present-mode
+ * sheets.
+ *
+ * Where {@linkcode PluginPresentationAnnotateApi} is fire-and-forget (every call
+ * creates a new shape), this namespace keys each shape by a caller-chosen
+ * string, so rerunning an analysis **updates** its sheet output in place instead
+ * of duplicating it:
+ *
+ * - {@linkcode PluginPresentationShapesApi.upsert} — create or update the shape for a key
+ * - {@linkcode PluginPresentationShapesApi.remove} — delete the shape for a key
+ * - {@linkcode PluginPresentationShapesApi.removeAll} — delete every shape owned by the calling plugin
+ * - {@linkcode PluginPresentationShapesApi.list} — the calling plugin's shapes (key, shapeId, type)
+ *
+ * Shape ids are derived deterministically from the plugin id + key, so upserts
+ * converge across collaborators. Mutations require **Present mode to be open**
+ * (`list` is a never-throw read); each plugin sees and mutates only its own
+ * shapes.
+ *
+ * Accessed via `snaptrude.presentation.shapes`.
+ */
+export abstract class PluginPresentationShapesApi {
+  constructor() {}
+
+  /**
+   * Create or update the shape for a key.
+   *
+   * The `shape` spec is a discriminated union over the same four annotation
+   * kinds as `presentation.annotate` (`text`, `note`, `arrow`, `geo`), with the
+   * same option shapes. On first call for a key the shape is created on the
+   * target sheet (`options.sheetId`, default: the first sheet) and nested under
+   * the sheet frame; on later calls the existing shape is updated in place —
+   * same shape id, same sheet, one undo step. Positions/bounds are relative to
+   * the sheet's top-left, in canvas units. Requires Present mode to be open.
+   *
+   * @param key - Caller-chosen stable identifier for the shape (per plugin).
+   * @param shape - The desired shape ({@linkcode PluginPresentationShapeSpec}):
+   *   `{ type: "text" | "note" | "arrow" | "geo", ... }` with the matching
+   *   annotate options. Changing `type` for an existing key replaces the shape
+   *   (same shape id).
+   * @param options - Optional `sheetId` — the sheet to create the shape on
+   *   (defaults to the first sheet; ignored on update, the shape stays on its
+   *   sheet).
+   * @returns A {@linkcode PluginPresentationShapesUpsertResult} — the stable
+   *   `shapeId` and `created` (`true` on first upsert, `false` on update).
+   * @throws If Present mode is not open, the args are invalid, or the sheet id
+   *   is unknown.
+   *
+   * @examplePrompt Update the analysis label on the sheet instead of adding another one
+   * @examplePrompt Rerun the daylight report and refresh its annotations
+   * @examplePrompt Keep one "FAR: 2.4" text on Sheet 1 that updates on each run
+   * @examplePrompt Draw a highlight rectangle the plugin can move on the next run
+   *
+   * # Example
+   * ```ts
+   * const { shapeId, created } = await snaptrude.presentation.shapes.upsert("far-label", {
+   *   type: "text",
+   *   text: "FAR: 2.4",
+   *   position: { x: 40, y: 40 },
+   *   color: "blue",
+   * })
+   * ```
+   */
+  public abstract upsert(
+    key: string,
+    shape: PluginPresentationShapeSpec,
+    options?: { sheetId?: string },
+  ): PluginApiReturn<PluginPresentationShapesUpsertResult>
+
+  /**
+   * Delete the shape for a key.
+   *
+   * Removes the calling plugin's shape registered under `key`, if it exists.
+   * Requires Present mode to be open.
+   *
+   * @param key - The key passed to {@linkcode PluginPresentationShapesApi.upsert}.
+   * @returns `true` if a shape was deleted, `false` if no shape exists for the
+   *   key.
+   * @throws If Present mode is not open or the key is invalid.
+   *
+   * @examplePrompt Remove the FAR label from the sheet
+   * @examplePrompt Delete the highlight the plugin added earlier
+   * @examplePrompt Clear the "far-label" annotation
+   *
+   * # Example
+   * ```ts
+   * const removed = await snaptrude.presentation.shapes.remove("far-label")
+   * ```
+   */
+  public abstract remove(key: string): PluginApiReturn<boolean>
+
+  /**
+   * Delete every shape owned by the calling plugin.
+   *
+   * Removes all shapes the calling plugin has upserted (across all sheets) in
+   * one undo step. Requires Present mode to be open.
+   *
+   * @returns The number of shapes deleted.
+   * @throws If Present mode is not open.
+   *
+   * @examplePrompt Clear all annotations my plugin added
+   * @examplePrompt Reset the sheet output before rerunning the analysis
+   * @examplePrompt Remove every plugin-drawn shape
+   *
+   * # Example
+   * ```ts
+   * const deleted = await snaptrude.presentation.shapes.removeAll()
+   * ```
+   */
+  public abstract removeAll(): PluginApiReturn<number>
+
+  /**
+   * List the calling plugin's shapes.
+   *
+   * Returns one entry per live shape the calling plugin has upserted — its
+   * `key`, the underlying canvas `shapeId`, and the shape `type`. A never-throw
+   * read: returns an empty list when Present mode is closed.
+   *
+   * @returns A {@linkcode PluginPresentationShapesListResult} with the `shapes`
+   *   array (empty when Present mode is closed).
+   *
+   * @examplePrompt Which annotations has my plugin placed on the sheets?
+   * @examplePrompt List the plugin's shapes before refreshing them
+   * @examplePrompt Check whether the FAR label already exists
+   *
+   * # Example
+   * ```ts
+   * const { shapes } = await snaptrude.presentation.shapes.list()
+   * const hasLabel = shapes.some((s) => s.key === "far-label")
+   * ```
+   */
+  public abstract list(): PluginApiReturn<PluginPresentationShapesListResult>
+}
+
+/**
+ * Desired shape for {@linkcode PluginPresentationShapesApi.upsert} — a
+ * discriminated union over the four annotate kinds, with the same option shapes
+ * as the matching `presentation.annotate` call:
+ *
+ * | `type` | Payload | Mirrors |
+ * |---|---|---|
+ * | `"text"` | `text`, `position?`, `size?`, `color?` | `annotate.text` |
+ * | `"note"` | `text`, `position?`, `color?`, `size?` | `annotate.note` |
+ * | `"arrow"` | `start`, `end`, `color?`, `size?` | `annotate.arrow` |
+ * | `"geo"` | `kind`, `bounds`, `color?`, `fill?` | `annotate.shape` |
+ *
+ * Positions/bounds are relative to the sheet's top-left, in canvas units.
+ */
+export const PluginPresentationShapeSpec = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("text"),
+    text: z.string(),
+    position: z.object({ x: z.number(), y: z.number() }).optional(),
+    size: PluginAnnotateTextSize.optional(),
+    color: PluginAnnotateTextColor.optional(),
+  }),
+  z.object({
+    type: z.literal("note"),
+    text: z.string(),
+    position: z.object({ x: z.number(), y: z.number() }).optional(),
+    color: PluginAnnotateTextColor.optional(),
+    size: PluginAnnotateTextSize.optional(),
+  }),
+  z.object({
+    type: z.literal("arrow"),
+    start: z.object({ x: z.number(), y: z.number() }),
+    end: z.object({ x: z.number(), y: z.number() }),
+    color: PluginAnnotateTextColor.optional(),
+    size: PluginAnnotateTextSize.optional(),
+  }),
+  z.object({
+    type: z.literal("geo"),
+    kind: PluginAnnotateGeoKind,
+    bounds: z.object({
+      x: z.number(),
+      y: z.number(),
+      w: z.number().positive(),
+      h: z.number().positive(),
+    }),
+    color: PluginAnnotateTextColor.optional(),
+    fill: PluginAnnotateFill.optional(),
+  }),
+])
+export type PluginPresentationShapeSpec = z.infer<
+  typeof PluginPresentationShapeSpec
+>
+
+/** The shape kind of a plugin-owned shape (the `type` discriminant of {@linkcode PluginPresentationShapeSpec}). */
+export const PluginPresentationShapeType = z.enum([
+  "text",
+  "note",
+  "arrow",
+  "geo",
+])
+export type PluginPresentationShapeType = z.infer<
+  typeof PluginPresentationShapeType
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationShapesApi.upsert}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `key` | `string` | Caller-chosen stable identifier (non-empty) |
+ * | `shape` | {@linkcode PluginPresentationShapeSpec} | The desired shape |
+ * | `sheetId` | `string \| undefined` | Sheet to create on (default: first sheet; ignored on update) |
+ */
+export const PluginPresentationShapesUpsertArgs = z.object({
+  key: z.string().min(1),
+  shape: PluginPresentationShapeSpec,
+  sheetId: z.string().optional(),
+})
+export type PluginPresentationShapesUpsertArgs = z.infer<
+  typeof PluginPresentationShapesUpsertArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationShapesApi.upsert}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapeId` | `string` | Stable id of the canvas shape for the key |
+ * | `created` | `boolean` | `true` if the shape was created, `false` if updated |
+ */
+export const PluginPresentationShapesUpsertResult = z.object({
+  shapeId: z.string(),
+  created: z.boolean(),
+})
+export type PluginPresentationShapesUpsertResult = z.infer<
+  typeof PluginPresentationShapesUpsertResult
+>
+
+/**
+ * Arguments for {@linkcode PluginPresentationShapesApi.remove}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `key` | `string` | The key the shape was upserted under (non-empty) |
+ */
+export const PluginPresentationShapesRemoveArgs = z.object({
+  key: z.string().min(1),
+})
+export type PluginPresentationShapesRemoveArgs = z.infer<
+  typeof PluginPresentationShapesRemoveArgs
+>
+
+/**
+ * Result of {@linkcode PluginPresentationShapesApi.list}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `shapes` | `{ key: string; shapeId: string; type: `{@linkcode PluginPresentationShapeType}` }[]` | One entry per live plugin-owned shape |
+ */
+export const PluginPresentationShapesListResult = z.object({
+  shapes: z.array(
+    z.object({
+      key: z.string(),
+      shapeId: z.string(),
+      type: PluginPresentationShapeType,
+    }),
+  ),
+})
+export type PluginPresentationShapesListResult = z.infer<
+  typeof PluginPresentationShapesListResult
+>