@snaptrude/plugin-core 0.7.0 → 0.8.0

package/src/api/entity/story.ts

@@ -102,21 +102,32 @@ export abstract class PluginStoryApi {
   ): PluginApiReturn<PluginStoryCreateResult>
 
   /**
-   * Update a story's floor-to-floor height, cascading the full geometry change.
+   * Update a story's floor-to-floor `height` and/or `name`.
    *
-   * This is the same operation as editing the height in the Stories panel: the
-   * walls, columns, and masses on the story are **stretched** to the new height,
-   * every story **above shifts up/down** by the delta so the stack stays
+   * **Height** is the same operation as editing the height in the Stories panel:
+   * the walls, columns, and masses on the story are **stretched** to the new
+   * height, every story **above shifts up/down** by the delta so the stack stays
    * contiguous, and coupled elements (staircases, parametric curtain walls,
-   * furniture offsets) are re-fitted. The whole cascade is committed as **one
-   * undo step**. Height-locked elements are left untouched.
+   * furniture offsets) are re-fitted. The whole height cascade is committed as
+   * **one undo step**. Height-locked elements are left untouched.
+   *
+   * **Name** is the same as renaming the story in the Stories panel: it is
+   * persisted immediately (saved to the project) but, mirroring the panel, is
+   * **not** part of the height undo step.
+   *
+   * At least one of `height` or `options.name` must be supplied. Omitting the
+   * `height` argument (e.g. for a rename-only update) leaves the height
+   * untouched.
    *
    * @param storyValue - Integer storey number
    *   identifying the story to update
    * @param height - New floor-to-floor height in
-   *   Babylon units
-   * @returns A {@linkcode PluginStoryUpdateResult} with the updated `storyValue` and `height`
+   *   Babylon units. Omit to leave the height unchanged.
+   * @param options - `name` (new display name for the story)
+   * @returns A {@linkcode PluginStoryUpdateResult} with the story's
+   *   `storyValue`, `height`, and `name` after the update
    * @throws `PRECONDITION_FAILED` if no story has the given value;
+   *   `VALIDATION` if neither `height` nor `options.name` is supplied;
    *   `STORY_HEIGHT_REJECTED` if the engine rejects the height (e.g. out of
    *   range — the change silently reverts host-side and is surfaced as this
    *   error); `STORY_UPDATE_FAILED` if the story cannot be re-read after the
@@ -124,21 +135,77 @@ export abstract class PluginStoryApi {
    *
    * @examplePrompt Change the ground floor height to 3.5 metres
    * @examplePrompt Make the second storey taller
+   * @examplePrompt Rename the ground floor to "Lobby"
    * @examplePrompt Set the floor-to-floor height of level 1
-   * @examplePrompt Increase the height of the third floor
+   * @examplePrompt Rename storey 2 and make it taller in one go
    *
    * # Example
    * ```ts
    * // Set ground floor height to 5 Babylon units — walls stretch and the
    * // floors above move up to match, all in a single undo step.
    * const result = await snaptrude.entity.story.update(1, 5)
+   * // Rename only, leaving the height untouched.
+   * await snaptrude.entity.story.update(1, undefined, { name: "Lobby" })
    * ```
    */
   public abstract update(
     storyValue: number,
-    height: number,
+    height?: number,
+    options?: { name?: string },
   ): PluginApiReturn<PluginStoryUpdateResult>
 
+  /**
+   * Make a story the active story — the same as clicking it in the storey/layer
+   * panel. Subsequent draws and creates target this story, and in 2D the
+   * viewport switches to it. This is a view/navigation change: it is **not**
+   * undoable and commits nothing to the model.
+   *
+   * @param storyValue - Integer storey number to activate
+   * @returns A {@linkcode PluginStorySetActiveResult} echoing the now-active `storyValue`
+   * @throws `PRECONDITION_FAILED` if no story has the given value
+   *
+   * @examplePrompt Switch to the second floor
+   * @examplePrompt Make the ground storey active
+   * @examplePrompt Go to the basement level
+   * @examplePrompt Set level 3 as the current storey
+   *
+   * # Example
+   * ```ts
+   * // Activate story 2, then draw a wall — it lands on story 2.
+   * await snaptrude.entity.story.setActive(2)
+   * ```
+   */
+  public abstract setActive(
+    storyValue: number,
+  ): PluginApiReturn<PluginStorySetActiveResult>
+
+  /**
+   * Delete a story and everything on it — the same as removing it from the
+   * storey panel. Every element placed on the story (walls, floors, masses, …)
+   * is deleted with it, the remaining stories are re-stacked, and the active
+   * story falls back to an adjacent one. Committed as a single undo step.
+   *
+   * @param storyValue - Integer storey number to delete
+   * @returns A {@linkcode PluginStoryDeleteResult} with the deleted `storyValue`
+   *   and the `newActiveStory` the editor fell back to
+   * @throws `PRECONDITION_FAILED` if no story has the given value; or if plugin
+   *   writes are disabled
+   *
+   * @examplePrompt Delete the top floor
+   * @examplePrompt Remove the basement level
+   * @examplePrompt Get rid of storey 3
+   * @examplePrompt Delete the second floor and everything on it
+   *
+   * # Example
+   * ```ts
+   * const { newActiveStory } = await snaptrude.entity.story.delete(3)
+   * console.log(`Deleted story 3; now on story ${newActiveStory}`)
+   * ```
+   */
+  public abstract delete(
+    storyValue: number,
+  ): PluginApiReturn<PluginStoryDeleteResult>
+
   /**
    * Duplicate a story into the adjacent level, up or down.
    *
@@ -301,35 +368,94 @@ export const PluginStoryCreateResult = z.object({
 export type PluginStoryCreateResult = z.infer<typeof PluginStoryCreateResult>
 
 /**
- * Arguments for {@linkcode PluginStoryApi.update}.
+ * Arguments for {@linkcode PluginStoryApi.update}. At least one of `height` or
+ * `name` must be supplied.
  *
  * | Property | Type | Description |
  * |---|---|---|
  * | `storyValue` | `number` (int) | Storey number of the story to update |
- * | `height` | `number` | New height in Babylon units |
+ * | `height` | `number?` | New height in Babylon units (omit to leave unchanged) |
+ * | `name` | `string?` | New display name for the story (omit to leave unchanged) |
  */
 export const PluginStoryUpdateArgs = z.object({
   storyValue: z.number().int(),
-  height: z.number(),
+  height: z.number().optional(),
+  name: z.string().optional(),
 })
 
 export type PluginStoryUpdateArgs = z.infer<typeof PluginStoryUpdateArgs>
 
 /**
- * Result of {@linkcode PluginStoryApi.update}.
+ * Result of {@linkcode PluginStoryApi.update} — the story's state after the update.
  *
  * | Property | Type | Description |
  * |---|---|---|
  * | `storyValue` | `number` | The storey number of the updated story |
- * | `height` | `number` | The new height after the update |
+ * | `height` | `number` | The height after the update |
+ * | `name` | `string` | The name after the update |
  */
 export const PluginStoryUpdateResult = z.object({
   storyValue: z.number(),
   height: z.number(),
+  name: z.string(),
 })
 
 export type PluginStoryUpdateResult = z.infer<typeof PluginStoryUpdateResult>
 
+/**
+ * Arguments for {@linkcode PluginStoryApi.setActive}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storyValue` | `number` (int) | Storey number to activate |
+ */
+export const PluginStorySetActiveArgs = z.object({
+  storyValue: z.number().int(),
+})
+
+export type PluginStorySetActiveArgs = z.infer<typeof PluginStorySetActiveArgs>
+
+/**
+ * Result of {@linkcode PluginStoryApi.setActive}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storyValue` | `number` | The storey number that is now active |
+ */
+export const PluginStorySetActiveResult = z.object({
+  storyValue: z.number(),
+})
+
+export type PluginStorySetActiveResult = z.infer<typeof PluginStorySetActiveResult>
+
+/**
+ * Arguments for {@linkcode PluginStoryApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storyValue` | `number` (int) | Storey number to delete |
+ */
+export const PluginStoryDeleteArgs = z.object({
+  storyValue: z.number().int(),
+})
+
+export type PluginStoryDeleteArgs = z.infer<typeof PluginStoryDeleteArgs>
+
+/**
+ * Result of {@linkcode PluginStoryApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storyValue` | `number` | The storey number that was deleted |
+ * | `newActiveStory` | `number` | The storey the editor fell back to as active |
+ */
+export const PluginStoryDeleteResult = z.object({
+  storyValue: z.number(),
+  newActiveStory: z.number(),
+})
+
+export type PluginStoryDeleteResult = z.infer<typeof PluginStoryDeleteResult>
+
 /**
  * Arguments for {@linkcode PluginStoryApi.duplicate} (options flattened).
  *