@snaptrude/plugin-core 0.0.0-bimsvg-20260928124803

package/src/api/design/visibility.ts

@@ -0,0 +1,143 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { ComponentHandle } from "../../handles"
+import { PluginDesignChangeResult } from "./lock"
+
+/**
+ * `snaptrude.design.visibility.*` — hide, isolate, and reveal scene entities.
+ *
+ * Visibility is a per-component user flag (the same one the "Hide" / "Isolate" /
+ * "Show All" toolbar and right-click actions toggle). Every method here commits
+ * an undoable command and echoes the affected entities as
+ * {@linkcode PluginDesignChangeResult}.
+ *
+ * Accessed via `snaptrude.design.visibility`.
+ */
+export abstract class PluginDesignVisibilityApi {
+  constructor() {}
+
+  /**
+   * Hide entities from the viewport — the same as the "Hide" action. Undoable.
+   * Hosted door/window/void children ride along with their wall. Already-hidden
+   * entities stay hidden.
+   *
+   * @param components Entities to hide
+   * @returns The affected entities (echoing the input handles)
+   *
+   * @examplePrompt Hide the selected walls
+   * @examplePrompt Conceal these masses so I can see behind them
+   * @examplePrompt Hide every column on this floor
+   * @examplePrompt Make this furniture disappear from view
+   *
+   * # Example
+   * ```ts
+   * const walls = await snaptrude.design.query.listWalls({ storeys: [1] })
+   * const { affected } = await snaptrude.design.visibility.hide(walls)
+   * ```
+   */
+  public abstract hide(
+    components: ComponentHandle[],
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Reveal specific hidden components — the inverse of
+   * {@linkcode PluginDesignVisibilityApi.hide}. Use
+   * {@linkcode PluginDesignVisibilityApi.showAll} to reveal everything.
+   *
+   * @param components - The components to reveal.
+   * @returns A {@linkcode PluginDesignChangeResult} echoing the components shown.
+   *
+   * @examplePrompt Show these walls again
+   * @examplePrompt Unhide the selected furniture
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.design.visibility.show([wall])
+   * ```
+   */
+  public abstract show(
+    components: ComponentHandle[],
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Isolate entities — hide everything else so only the given entities remain
+   * visible (the "Isolate" / solo action). Undoable. Reverse it with
+   * {@linkcode PluginDesignVisibilityApi.showAll}.
+   *
+   * @param components Entities to keep visible; everything else is hidden
+   * @returns The isolated entities (echoing the input handles)
+   *
+   * @examplePrompt Isolate the selected room so I can focus on it
+   * @examplePrompt Show only these walls and hide the rest
+   * @examplePrompt Solo this mass
+   * @examplePrompt Hide everything except the staircase
+   *
+   * # Example
+   * ```ts
+   * const [room] = await snaptrude.design.selection.get()
+   * await snaptrude.design.visibility.isolate([room])
+   * ```
+   */
+  public abstract isolate(
+    components: ComponentHandle[],
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Reveal everything hidden on the active story — the "Show All" action, which
+   * also exits an isolate. Undoable.
+   *
+   * @returns The entities that were made visible
+   *
+   * @examplePrompt Show everything again
+   * @examplePrompt Unhide all the hidden objects
+   * @examplePrompt Exit isolate mode
+   * @examplePrompt Reveal everything I hid earlier
+   *
+   * # Example
+   * ```ts
+   * const { affected } = await snaptrude.design.visibility.showAll()
+   * console.log(`Revealed ${affected.length} entities`)
+   * ```
+   */
+  public abstract showAll(): PluginApiReturn<PluginDesignChangeResult>
+}
+
+/**
+ * Arguments for {@linkcode PluginDesignVisibilityApi.hide}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | Entities to hide |
+ */
+export const PluginDesignVisibilityHideArgs = z.object({
+  components: z.array(ComponentHandle),
+})
+export type PluginDesignVisibilityHideArgs = z.infer<typeof PluginDesignVisibilityHideArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignVisibilityApi.show}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | Entities to reveal |
+ */
+export const PluginDesignVisibilityShowArgs = z.object({
+  components: z.array(ComponentHandle),
+})
+export type PluginDesignVisibilityShowArgs = z.infer<
+  typeof PluginDesignVisibilityShowArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginDesignVisibilityApi.isolate}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `components` | {@linkcode ComponentHandle}`[]` | Entities to keep visible |
+ */
+export const PluginDesignVisibilityIsolateArgs = z.object({
+  components: z.array(ComponentHandle),
+})
+export type PluginDesignVisibilityIsolateArgs = z.infer<
+  typeof PluginDesignVisibilityIsolateArgs
+>

package/src/api/design/windows/index.ts

@@ -0,0 +1,333 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { ComponentHandle } from "../../../handles"
+import { PluginDesignChangeResult } from "../lock"
+import { PluginObjectCatalogGroup, PluginObjectCatalogItem } from "../doors"
+
+/**
+ * `snaptrude.design.windows` — window-specific reads. Creation lives at
+ * `design.create.window`; generic reads (`listWindows`/`getHost`/`getProperties`) live
+ * at `design.query.*`. Window targets are {@linkcode ComponentHandle}s.
+ *
+ * The **catalog** reads (`listCatalogGroups`/`listCatalog`/`getCatalogItem`/`exists`)
+ * browse the placeable window library — plain value records keyed by a library id
+ * (team `_id` or general `fullName`), NOT handles — and feed `design.create.window`.
+ * They are network-backed but carry no `Async` suffix (§6.6) and never throw
+ * (`[]`/`null`). The {@linkcode PluginObjectCatalogGroup} / {@linkcode PluginObjectCatalogItem}
+ * DTOs are shared with `design.doors` (defined there, re-exported here).
+ *
+ * `getSillHeight` (bounds-derived) and the command-wired `mirror` land in a later pass.
+ */
+export abstract class PluginDesignWindowsApi {
+  constructor() {}
+
+  /**
+   * Get the type name of a window — the label that identifies which kind of
+   * window the instance is, as shown in its properties.
+   *
+   * @param window The window to query
+   * @returns The type as a `string`, or `null`
+   *
+   * @examplePrompt What type of window is this?
+   * @examplePrompt Is the selected window a casement or a slider?
+   * @examplePrompt Tell me the window type used on this wall
+   * @examplePrompt Check what kind of window the living room has
+   *
+   * # Example
+   * ```ts
+   * const [win] = await snaptrude.design.query.listWindows({ isSelected: true })
+   * const type = await snaptrude.design.windows.getType(win)
+   * if (type) console.log("window type:", type)
+   * ```
+   */
+  public abstract getType(window: ComponentHandle): PluginApiReturn<string | null>
+
+  /**
+   * Get the width of a window — how wide its opening is along the host wall.
+   *
+   * @param window The window to query
+   * @returns The width as a `number`, or `null`
+   *
+   * @examplePrompt How wide is this window?
+   * @examplePrompt What's the width of the selected window?
+   * @examplePrompt Measure the width of the kitchen window
+   * @examplePrompt Check whether this window is 1200mm wide
+   *
+   * # Example
+   * ```ts
+   * const [win] = await snaptrude.design.query.listWindows()
+   * const width = await snaptrude.design.windows.getWidth(win)
+   * if (width !== null) console.log("window width:", width)
+   * ```
+   */
+  public abstract getWidth(window: ComponentHandle): PluginApiReturn<number | null>
+
+  /**
+   * Get the height of a window — how tall its opening is on the host wall.
+   *
+   * @param window The window to query
+   * @returns The height as a `number`, or `null`
+   *
+   * @examplePrompt How tall is this window?
+   * @examplePrompt What's the height of the selected window?
+   * @examplePrompt Check the window height on this wall
+   * @examplePrompt Is the bedroom window 1.5m high?
+   *
+   * # Example
+   * ```ts
+   * const [win] = await snaptrude.design.query.listWindows()
+   * const height = await snaptrude.design.windows.getHeight(win)
+   * if (height !== null) console.log("window height:", height)
+   * ```
+   */
+  public abstract getHeight(window: ComponentHandle): PluginApiReturn<number | null>
+
+  /**
+   * Get a window's full dimensions in one call — width along the wall, vertical
+   * height, and thickness through the wall — measured in the window's local
+   * oriented space.
+   *
+   * @param window The window to query
+   * @returns The dimensions, or `null`
+   *
+   * @examplePrompt What are the dimensions of this window?
+   * @examplePrompt How big is the selected window?
+   * @examplePrompt Give me the width, height and depth of this window
+   * @examplePrompt Measure the living room window
+   * @examplePrompt Get the window size including its thickness through the wall
+   *
+   * # Example
+   * ```ts
+   * const [win] = await snaptrude.design.query.listWindows({ isSelected: true })
+   * const dims = await snaptrude.design.windows.getDimensions(win)
+   * if (dims) console.log(dims.width, dims.height, dims.thickness)
+   * ```
+   */
+  public abstract getDimensions(
+    window: ComponentHandle
+  ): PluginApiReturn<PluginWindowDimensions | null>
+
+  /**
+   * Set the width of a window, resizing its opening and re-cutting the host
+   * wall. Width is in engine units; the change is undoable.
+   *
+   * @param window The window to resize
+   * @param width New width (engine units)
+   * @returns The affected window
+   *
+   * @examplePrompt Make this window 1200mm wide
+   * @examplePrompt Widen the selected window to 4 feet
+   * @examplePrompt Change the window width to 1.5m
+   * @examplePrompt Resize the kitchen window to 900 wide
+   *
+   * # Example
+   * ```ts
+   * // Takes a single window (unlike design.doors.setWidth, which takes an array)
+   * const [win] = await snaptrude.design.query.listWindows({ isSelected: true })
+   * const { affected } = await snaptrude.design.windows.setWidth(win, 1200)
+   * ```
+   */
+  public abstract setWidth(
+    window: ComponentHandle,
+    width: number
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * Set the height of a window, resizing its opening and re-cutting the host
+   * wall. Height is in engine units; the change is undoable.
+   *
+   * @param window The window to resize
+   * @param height New height (engine units)
+   * @returns The affected window
+   *
+   * @examplePrompt Make this window 1.5m tall
+   * @examplePrompt Change the window height to 4 feet
+   * @examplePrompt Shorten the selected window to 900mm high
+   * @examplePrompt Set the bedroom window height to 1200
+   *
+   * # Example
+   * ```ts
+   * const [win] = await snaptrude.design.query.listWindows({ isSelected: true })
+   * await snaptrude.design.windows.setHeight(win, 1500)
+   * ```
+   */
+  public abstract setHeight(
+    window: ComponentHandle,
+    height: number
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * List the window catalog **groups** — the placement families (Fixed,
+   * Casement, Sliding, Folding, …), built-in groups merged with any
+   * team-custom types.
+   *
+   * @returns The groups as {@linkcode PluginObjectCatalogGroup}`[]` (`[]` when empty)
+   *
+   * @examplePrompt What kinds of windows can I place?
+   * @examplePrompt List the window groups in the catalog
+   * @examplePrompt Show me the window families available in this project
+   * @examplePrompt Which window types does this project support?
+   *
+   * # Example
+   * ```ts
+   * const groups = await snaptrude.design.windows.listCatalogGroups()
+   * for (const g of groups) console.log(g.dbType, g.label, g.source)
+   * ```
+   */
+  public abstract listCatalogGroups(): PluginApiReturn<PluginObjectCatalogGroup[]>
+
+  /**
+   * List the placeable window catalog (team + general libraries), optionally
+   * restricted to one group by its `dbType` token.
+   *
+   * @param group Restrict to one group's `dbType` (optional; e.g. `"casementDouble"`)
+   * @returns The catalog as {@linkcode PluginObjectCatalogItem}`[]` (`[]` when empty)
+   *
+   * @examplePrompt What windows can I place in this project?
+   * @examplePrompt List every window in the library
+   * @examplePrompt Show me the casement windows I can add
+   * @examplePrompt Browse the window catalog
+   *
+   * # Example
+   * ```ts
+   * const [group] = await snaptrude.design.windows.listCatalogGroups()
+   * const items = await snaptrude.design.windows.listCatalog(group?.dbType)
+   * for (const item of items) console.log(item.id, item.name, item.thumbnailUrl)
+   * ```
+   */
+  public abstract listCatalog(
+    group?: string
+  ): PluginApiReturn<PluginObjectCatalogItem[]>
+
+  /**
+   * Get a single window catalog item by its library id.
+   *
+   * @param id The catalog library id
+   * @returns The item, or `null` if no catalog item matches
+   *
+   * @examplePrompt Get the details of this window from the library
+   * @examplePrompt Look up the catalog entry for this window id
+   * @examplePrompt What is the cost of this window item?
+   * @examplePrompt Show me the family name of this window in the catalog
+   *
+   * # Example
+   * ```ts
+   * const [entry] = await snaptrude.design.windows.listCatalog()
+   * const item = await snaptrude.design.windows.getCatalogItem(entry.id)
+   * if (item) console.log(item.name, item.source, item.dbType)
+   * ```
+   */
+  public abstract getCatalogItem(
+    id: string
+  ): PluginApiReturn<PluginObjectCatalogItem | null>
+
+  /**
+   * Test whether a window catalog item exists for the given library id.
+   *
+   * @param id The catalog library id
+   * @returns `true` if it exists, otherwise `false`
+   *
+   * @examplePrompt Is this window still in the library?
+   * @examplePrompt Check whether a window catalog item with this id exists
+   * @examplePrompt Does my team library have this window?
+   * @examplePrompt Verify the window is available before placing it
+   *
+   * # Example
+   * ```ts
+   * const [entry] = await snaptrude.design.windows.listCatalog()
+   * const stillAvailable = await snaptrude.design.windows.exists(entry.id)
+   * console.log(stillAvailable ? "safe to place" : "removed from library")
+   * ```
+   */
+  public abstract exists(id: string): PluginApiReturn<boolean>
+}
+
+/**
+ * Arguments for the single-window read methods.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `window` | {@linkcode ComponentHandle} | The window to query |
+ */
+export const PluginDesignWindowArgs = z.object({
+  window: ComponentHandle,
+})
+export type PluginDesignWindowArgs = z.infer<typeof PluginDesignWindowArgs>
+
+/**
+ * A window's dimensions.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `width` | `number` | Along the wall |
+ * | `height` | `number` | Vertical |
+ * | `thickness` | `number` | Through the wall (engine `length` axis) |
+ */
+export const PluginWindowDimensions = z.object({
+  width: z.number(),
+  height: z.number(),
+  thickness: z.number(),
+})
+export type PluginWindowDimensions = z.infer<typeof PluginWindowDimensions>
+
+/**
+ * Arguments for {@linkcode PluginDesignWindowsApi.setWidth}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `window` | {@linkcode ComponentHandle} | The window to resize |
+ * | `width` | `number` | New width (engine units) |
+ */
+export const PluginDesignWindowSetWidthArgs = z.object({
+  window: ComponentHandle,
+  width: z.number(),
+})
+export type PluginDesignWindowSetWidthArgs = z.infer<typeof PluginDesignWindowSetWidthArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignWindowsApi.setHeight}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `window` | {@linkcode ComponentHandle} | The window to resize |
+ * | `height` | `number` | New height (engine units) |
+ */
+export const PluginDesignWindowSetHeightArgs = z.object({
+  window: ComponentHandle,
+  height: z.number(),
+})
+export type PluginDesignWindowSetHeightArgs = z.infer<typeof PluginDesignWindowSetHeightArgs>
+
+// ---------------------------------------------------------------------------
+// catalog (shared DTOs defined in ../doors, re-exported here for symmetry)
+// ---------------------------------------------------------------------------
+
+// Re-export the shared catalog DTOs imported at the top of this file.
+export { PluginObjectCatalogGroup, PluginObjectCatalogItem }
+
+/**
+ * Arguments for {@linkcode PluginDesignWindowsApi.listCatalog}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `group` | `string`? | Restrict to one group's `dbType` token (optional) |
+ */
+export const PluginDesignWindowListCatalogArgs = z.object({
+  group: z.string().optional(),
+})
+export type PluginDesignWindowListCatalogArgs = z.infer<typeof PluginDesignWindowListCatalogArgs>
+
+/**
+ * Arguments for {@linkcode PluginDesignWindowsApi.getCatalogItem} / {@linkcode PluginDesignWindowsApi.exists}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The catalog library id |
+ */
+export const PluginDesignWindowGetCatalogItemArgs = z.object({
+  id: z.string(),
+})
+export type PluginDesignWindowGetCatalogItemArgs = z.infer<typeof PluginDesignWindowGetCatalogItemArgs>
+
+export const PluginDesignWindowExistsArgs = PluginDesignWindowGetCatalogItemArgs
+export type PluginDesignWindowExistsArgs = z.infer<typeof PluginDesignWindowExistsArgs>