@snaptrude/plugin-core 0.11.0-rc.1 → 1.0.0

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

@@ -8,16 +8,15 @@ import { PluginDesignChangeResult } from "../lock"
  * `design.create.door`; generic reads (`listDoors`/`getHost`/`getProperties`) live at
  * `design.query.*`. Door targets are {@linkcode ComponentHandle}s.
  *
- * `getSwingDirection` is a DERIVED read (no persisted field) — computed from the door
- * mesh reflection state. `mirror` reflects the door across an axis (undoable, one
- * command); `setType` is intentionally absent (the engine has no in-place re-type —
- * it would require delete+recreate).
+ * PC-only: dimensions read the evaluated opening. Setters write declared width/height
+ * parameters, never mesh scale. Missing or derived controls reject. Linked copies follow
+ * the shared edit. Use design.family.setParameters for other parameters.
+ * getSwingDirection reads hand. mirror changes declared swing or hand controls.
  *
  * The **catalog** reads (`listCatalogGroups`/`listCatalog`/`getCatalogItem`/`exists`)
- * browse the placeable door library — plain value records keyed by a library id
- * (team `_id` or general `fullName`), NOT handles — and feed `design.create.door`.
- * They are network-backed but carry no `Async` suffix (§6.6) and never throw
- * (`[]`/`null`). The {@linkcode PluginObjectCatalogGroup} / {@linkcode PluginObjectCatalogItem}
+ * browse saved hosted door families, keyed by definition ID, and feed design.create.door.
+ * They reject if saved definitions cannot be loaded completely. A missing item returns null.
+ * The {@linkcode PluginObjectCatalogGroup} / {@linkcode PluginObjectCatalogItem}
  * DTOs are shared with `design.windows`.
  */
 export abstract class PluginDesignDoorsApi {
@@ -63,7 +62,9 @@ export abstract class PluginDesignDoorsApi {
    * if (family) console.log("family:", family)
    * ```
    */
-  public abstract getFamily(door: ComponentHandle): PluginApiReturn<string | null>
+  public abstract getFamily(
+    door: ComponentHandle,
+  ): PluginApiReturn<string | null>
 
   /**
    * Get the width of a door — how wide its opening is along the host wall.
@@ -83,7 +84,9 @@ export abstract class PluginDesignDoorsApi {
    * if (width !== null) console.log("door width:", width)
    * ```
    */
-  public abstract getWidth(door: ComponentHandle): PluginApiReturn<number | null>
+  public abstract getWidth(
+    door: ComponentHandle,
+  ): PluginApiReturn<number | null>
 
   /**
    * Get the height of a door — how tall its opening is from base to head.
@@ -103,12 +106,13 @@ export abstract class PluginDesignDoorsApi {
    * if (height !== null) console.log("door height:", height)
    * ```
    */
-  public abstract getHeight(door: ComponentHandle): PluginApiReturn<number | null>
+  public abstract getHeight(
+    door: ComponentHandle,
+  ): PluginApiReturn<number | null>
 
   /**
-   * Get a door's full dimensions in one call — width along the wall, vertical
-   * height, and thickness through the wall — measured in the door's local
-   * oriented space. Parity with {@linkcode PluginDesignWindowsApi.getDimensions}.
+   * Get evaluated opening width/height and host thickness, in Snaptrude units.
+   * The opening can include allowances beyond the width/height input parameters.
    *
    * @param door The door to query
    * @returns The dimensions, or `null`
@@ -126,12 +130,12 @@ export abstract class PluginDesignDoorsApi {
    * ```
    */
   public abstract getDimensions(
-    door: ComponentHandle
+    door: ComponentHandle,
   ): PluginApiReturn<PluginDoorDimensions | null>
 
   /**
-   * Get the floor a door is hosted on — the storey/level component that
-   * supports the door.
+   * Returns null for recipe doors. Room floors own doorway infill; there is
+   * no separate support-floor entity.
    *
    * @param door The door to query
    * @returns The support floor {@linkcode ComponentHandle}, or `null`
@@ -151,12 +155,13 @@ export abstract class PluginDesignDoorsApi {
    * }
    * ```
    */
-  public abstract getSupportFloor(door: ComponentHandle): PluginApiReturn<ComponentHandle | null>
+  public abstract getSupportFloor(
+    door: ComponentHandle,
+  ): PluginApiReturn<ComponentHandle | null>
 
   /**
-   * Get a door's swing (hinge) handedness — whether it opens as a left-hand or
-   * right-hand door. Derived from the door mesh's reflection state, not a
-   * persisted field.
+   * Read the saved hand parameter. left means local -X; right means local +X.
+   * Returns null when the recipe does not declare that control.
    *
    * @param door The door to query
    * @returns `'left'` / `'right'`, or `null` if indeterminate
@@ -174,15 +179,18 @@ export abstract class PluginDesignDoorsApi {
    * ```
    */
   public abstract getSwingDirection(
-    door: ComponentHandle
+    door: ComponentHandle,
   ): PluginApiReturn<"left" | "right" | null>
 
   /**
-   * Mirror a door across an axis, flipping its swing so it opens from the
-   * other side. Undoable as a single command.
+   * Change authored controls in one undo step: x (default) toggles swing
+   * front/back; z toggles hand left/right. The recipe must declare these enums.
+   * Axis y rejects. No mesh reflection occurs. Recipes use outputs.swingSide
+   * (1 or -1) for the adjoining room's floor ownership. A door between two
+   * room floors requires this output; a missing or invalid report rejects the cut.
    *
    * @param door The door to mirror
-   * @param axis Reflection axis (optional; default `'x'` — the swing-flip axis)
+   * @param axis Reflection axis (optional; default `'x'` — the swing-flip axis; `'z'` — the hinge-jamb axis)
    * @returns The affected door(s)
    *
    * @examplePrompt Flip this door's swing
@@ -193,15 +201,16 @@ export abstract class PluginDesignDoorsApi {
    *
    * # Example
    * ```ts
-   * // Flip the selected door's swing — axis defaults to "x" (the swing-flip
-   * // axis); pass "y" or "z" to reflect across a different axis
+   * // Flip the selected door's swing side — axis defaults to "x"
    * const [door] = await snaptrude.design.query.listDoors({ isSelected: true })
    * const { affected } = await snaptrude.design.doors.mirror(door)
+   * // …or swap the hinged jamb instead (keeps the swing side)
+   * await snaptrude.design.doors.mirror(door, "z")
    * ```
    */
   public abstract mirror(
     door: ComponentHandle,
-    axis?: PluginMirrorAxis
+    axis?: PluginMirrorAxis,
   ): PluginApiReturn<PluginDesignChangeResult>
 
   /**
@@ -228,7 +237,7 @@ export abstract class PluginDesignDoorsApi {
    */
   public abstract setWidth(
     doors: ComponentHandle[],
-    width: number
+    width: number,
   ): PluginApiReturn<PluginDesignChangeResult>
 
   /**
@@ -253,7 +262,7 @@ export abstract class PluginDesignDoorsApi {
    */
   public abstract setHeight(
     doors: ComponentHandle[],
-    height: number
+    height: number,
   ): PluginApiReturn<PluginDesignChangeResult>
 
   /**
@@ -273,7 +282,9 @@ export abstract class PluginDesignDoorsApi {
    * for (const g of groups) console.log(g.dbType, g.label, g.source)
    * ```
    */
-  public abstract listCatalogGroups(): PluginApiReturn<PluginObjectCatalogGroup[]>
+  public abstract listCatalogGroups(): PluginApiReturn<
+    PluginObjectCatalogGroup[]
+  >
 
   /**
    * List the placeable door catalog (team + general libraries), optionally
@@ -295,7 +306,7 @@ export abstract class PluginDesignDoorsApi {
    * ```
    */
   public abstract listCatalog(
-    group?: string
+    group?: string,
   ): PluginApiReturn<PluginObjectCatalogItem[]>
 
   /**
@@ -317,7 +328,7 @@ export abstract class PluginDesignDoorsApi {
    * ```
    */
   public abstract getCatalogItem(
-    id: string
+    id: string,
   ): PluginApiReturn<PluginObjectCatalogItem | null>
 
   /**
@@ -369,7 +380,7 @@ export const PluginDoorDimensions = z.object({
 })
 export type PluginDoorDimensions = z.infer<typeof PluginDoorDimensions>
 
-/** Mirror axis — tokens mirror the engine `FlipDirection` verbatim (§6.1). */
+/** Mirror axis — tokens mirror the engine `FlipDirection` verbatim: `'x'` flips the swing side, `'z'` swaps the hinged jamb, `'y'` turns the door upside down. */
 export const PluginMirrorAxis = z.enum(["x", "y", "z"])
 export type PluginMirrorAxis = z.infer<typeof PluginMirrorAxis>
 
@@ -379,13 +390,15 @@ export type PluginMirrorAxis = z.infer<typeof PluginMirrorAxis>
  * | Property | Type | Description |
  * |---|---|---|
  * | `door` | {@linkcode ComponentHandle} | The door to mirror |
- * | `axis` | {@linkcode PluginMirrorAxis} | Reflection axis (optional; default `'x'` — the swing-flip axis) |
+ * | `axis` | {@linkcode PluginMirrorAxis} | Reflection axis (optional; default `'x'` — the swing-flip axis; `'z'` — the hinge-jamb axis) |
  */
 export const PluginDesignDoorMirrorArgs = z.object({
   door: ComponentHandle,
   axis: PluginMirrorAxis.optional(),
 })
-export type PluginDesignDoorMirrorArgs = z.infer<typeof PluginDesignDoorMirrorArgs>
+export type PluginDesignDoorMirrorArgs = z.infer<
+  typeof PluginDesignDoorMirrorArgs
+>
 
 /**
  * Arguments for {@linkcode PluginDesignDoorsApi.setWidth}.
@@ -399,7 +412,9 @@ export const PluginDesignDoorSetWidthArgs = z.object({
   doors: z.array(ComponentHandle),
   width: z.number(),
 })
-export type PluginDesignDoorSetWidthArgs = z.infer<typeof PluginDesignDoorSetWidthArgs>
+export type PluginDesignDoorSetWidthArgs = z.infer<
+  typeof PluginDesignDoorSetWidthArgs
+>
 
 /**
  * Arguments for {@linkcode PluginDesignDoorsApi.setHeight}.
@@ -413,7 +428,9 @@ export const PluginDesignDoorSetHeightArgs = z.object({
   doors: z.array(ComponentHandle),
   height: z.number(),
 })
-export type PluginDesignDoorSetHeightArgs = z.infer<typeof PluginDesignDoorSetHeightArgs>
+export type PluginDesignDoorSetHeightArgs = z.infer<
+  typeof PluginDesignDoorSetHeightArgs
+>
 
 // ---------------------------------------------------------------------------
 // catalog (shared by doors + windows)
@@ -475,7 +492,9 @@ export type PluginObjectCatalogItem = z.infer<typeof PluginObjectCatalogItem>
 export const PluginDesignDoorListCatalogArgs = z.object({
   group: z.string().optional(),
 })
-export type PluginDesignDoorListCatalogArgs = z.infer<typeof PluginDesignDoorListCatalogArgs>
+export type PluginDesignDoorListCatalogArgs = z.infer<
+  typeof PluginDesignDoorListCatalogArgs
+>
 
 /**
  * Arguments for {@linkcode PluginDesignDoorsApi.getCatalogItem} / {@linkcode PluginDesignDoorsApi.exists}.
@@ -487,7 +506,11 @@ export type PluginDesignDoorListCatalogArgs = z.infer<typeof PluginDesignDoorLis
 export const PluginDesignDoorGetCatalogItemArgs = z.object({
   id: z.string(),
 })
-export type PluginDesignDoorGetCatalogItemArgs = z.infer<typeof PluginDesignDoorGetCatalogItemArgs>
+export type PluginDesignDoorGetCatalogItemArgs = z.infer<
+  typeof PluginDesignDoorGetCatalogItemArgs
+>
 
 export const PluginDesignDoorExistsArgs = PluginDesignDoorGetCatalogItemArgs
-export type PluginDesignDoorExistsArgs = z.infer<typeof PluginDesignDoorExistsArgs>
+export type PluginDesignDoorExistsArgs = z.infer<
+  typeof PluginDesignDoorExistsArgs
+>