@snaptrude/plugin-core 0.7.0 → 0.8.0

package/dist/api/entity/story.d.ts

@@ -91,21 +91,32 @@ export declare abstract class PluginStoryApi {
      */
     abstract create(storyValue: number, height?: number): 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
@@ -113,17 +124,68 @@ export declare 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" })
      * ```
      */
-    abstract update(storyValue: number, height: number): PluginApiReturn<PluginStoryUpdateResult>;
+    abstract update(storyValue: 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)
+     * ```
+     */
+    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}`)
+     * ```
+     */
+    abstract delete(storyValue: number): PluginApiReturn<PluginStoryDeleteResult>;
     /**
      * Duplicate a story into the adjacent level, up or down.
      *
@@ -278,31 +340,82 @@ export declare const PluginStoryCreateResult: z.ZodObject<{
 }, z.core.$strip>;
 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 declare const PluginStoryUpdateArgs: z.ZodObject<{
     storyValue: z.ZodNumber;
-    height: z.ZodNumber;
+    height: z.ZodOptional<z.ZodNumber>;
+    name: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 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 declare const PluginStoryUpdateResult: z.ZodObject<{
     storyValue: z.ZodNumber;
     height: z.ZodNumber;
+    name: z.ZodString;
 }, z.core.$strip>;
 export type PluginStoryUpdateResult = z.infer<typeof PluginStoryUpdateResult>;
+/**
+ * Arguments for {@linkcode PluginStoryApi.setActive}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storyValue` | `number` (int) | Storey number to activate |
+ */
+export declare const PluginStorySetActiveArgs: z.ZodObject<{
+    storyValue: z.ZodNumber;
+}, z.core.$strip>;
+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 declare const PluginStorySetActiveResult: z.ZodObject<{
+    storyValue: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginStorySetActiveResult = z.infer<typeof PluginStorySetActiveResult>;
+/**
+ * Arguments for {@linkcode PluginStoryApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `storyValue` | `number` (int) | Storey number to delete |
+ */
+export declare const PluginStoryDeleteArgs: z.ZodObject<{
+    storyValue: z.ZodNumber;
+}, z.core.$strip>;
+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 declare const PluginStoryDeleteResult: z.ZodObject<{
+    storyValue: z.ZodNumber;
+    newActiveStory: z.ZodNumber;
+}, z.core.$strip>;
+export type PluginStoryDeleteResult = z.infer<typeof PluginStoryDeleteResult>;
 /**
  * Arguments for {@linkcode PluginStoryApi.duplicate} (options flattened).
  *

package/dist/api/entity/story.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"story.d.ts","sourceRoot":"","sources":["../../../src/api/entity/story.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"story.d.ts","sourceRoot":"","sources":["../../../src/api/entity/story.ts"],"names":[],"mappings":"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"}