@snaptrude/plugin-core 0.9.16-networks-20261012.1 → 0.9.17

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

@@ -8,15 +8,18 @@ import { PluginDesignChangeResult } from "../lock"
  * `design.create.door`; generic reads (`listDoors`/`getHost`/`getProperties`) live at
  * `design.query.*`. Door targets are {@linkcode ComponentHandle}s.
  *
- * 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.
+ * `getSwingDirection` is a DERIVED read (no persisted field) — computed from the placed
+ * mesh's orientation: stand on the side the door swings open to, facing it; `'left'`
+ * when the hinged jamb is on your left. `mirror` reflects the door about one of its own
+ * axes (undoable, one command): `'x'` flips the swing side, `'z'` swaps the hinged jamb;
+ * `setType` is intentionally absent (the engine has no in-place re-type —
+ * it would require delete+recreate).
  *
  * The **catalog** reads (`listCatalogGroups`/`listCatalog`/`getCatalogItem`/`exists`)
- * 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}
+ * 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}
  * DTOs are shared with `design.windows`.
  */
 export abstract class PluginDesignDoorsApi {
@@ -62,9 +65,7 @@ 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.
@@ -84,9 +85,7 @@ 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.
@@ -106,13 +105,12 @@ 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 evaluated opening width/height and host thickness, in Snaptrude units.
-   * The opening can include allowances beyond the width/height input parameters.
+   * 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}.
    *
    * @param door The door to query
    * @returns The dimensions, or `null`
@@ -130,12 +128,12 @@ export abstract class PluginDesignDoorsApi {
    * ```
    */
   public abstract getDimensions(
-    door: ComponentHandle,
+    door: ComponentHandle
   ): PluginApiReturn<PluginDoorDimensions | null>
 
   /**
-   * Returns null for recipe doors. Room floors own doorway infill; there is
-   * no separate support-floor entity.
+   * Get the floor a door is hosted on — the storey/level component that
+   * supports the door.
    *
    * @param door The door to query
    * @returns The support floor {@linkcode ComponentHandle}, or `null`
@@ -155,13 +153,14 @@ export abstract class PluginDesignDoorsApi {
    * }
    * ```
    */
-  public abstract getSupportFloor(
-    door: ComponentHandle,
-  ): PluginApiReturn<ComponentHandle | null>
+  public abstract getSupportFloor(door: ComponentHandle): PluginApiReturn<ComponentHandle | null>
 
   /**
-   * Read the saved hand parameter. left means local -X; right means local +X.
-   * Returns null when the recipe does not declare that control.
+   * Get a door's swing (hinge) handedness. Stand on the side the door swings
+   * open to, facing the door: `'left'` when the hinged jamb is on your left,
+   * `'right'` when it is on your right. Derived from the placed mesh's
+   * orientation (the same reflection `mirror` and the `hinge` placement option
+   * apply), not a persisted field.
    *
    * @param door The door to query
    * @returns `'left'` / `'right'`, or `null` if indeterminate
@@ -179,15 +178,14 @@ export abstract class PluginDesignDoorsApi {
    * ```
    */
   public abstract getSwingDirection(
-    door: ComponentHandle,
+    door: ComponentHandle
   ): PluginApiReturn<"left" | "right" | null>
 
   /**
-   * 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.
+   * Mirror a door about its own axes. `'x'` (default) flips the swing side —
+   * the door opens to the other side of the wall; `'z'` swaps the hinged jamb
+   * (left-hand ↔ right-hand, same swing side); `'y'` turns it upside down.
+   * Undoable as a single command.
    *
    * @param door The door to mirror
    * @param axis Reflection axis (optional; default `'x'` — the swing-flip axis; `'z'` — the hinge-jamb axis)
@@ -210,7 +208,7 @@ export abstract class PluginDesignDoorsApi {
    */
   public abstract mirror(
     door: ComponentHandle,
-    axis?: PluginMirrorAxis,
+    axis?: PluginMirrorAxis
   ): PluginApiReturn<PluginDesignChangeResult>
 
   /**
@@ -237,7 +235,7 @@ export abstract class PluginDesignDoorsApi {
    */
   public abstract setWidth(
     doors: ComponentHandle[],
-    width: number,
+    width: number
   ): PluginApiReturn<PluginDesignChangeResult>
 
   /**
@@ -262,7 +260,7 @@ export abstract class PluginDesignDoorsApi {
    */
   public abstract setHeight(
     doors: ComponentHandle[],
-    height: number,
+    height: number
   ): PluginApiReturn<PluginDesignChangeResult>
 
   /**
@@ -282,9 +280,7 @@ 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
@@ -306,7 +302,7 @@ export abstract class PluginDesignDoorsApi {
    * ```
    */
   public abstract listCatalog(
-    group?: string,
+    group?: string
   ): PluginApiReturn<PluginObjectCatalogItem[]>
 
   /**
@@ -328,7 +324,7 @@ export abstract class PluginDesignDoorsApi {
    * ```
    */
   public abstract getCatalogItem(
-    id: string,
+    id: string
   ): PluginApiReturn<PluginObjectCatalogItem | null>
 
   /**
@@ -396,9 +392,7 @@ 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}.
@@ -412,9 +406,7 @@ 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}.
@@ -428,9 +420,7 @@ 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)
@@ -492,9 +482,7 @@ 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}.
@@ -506,11 +494,7 @@ export type PluginDesignDoorListCatalogArgs = z.infer<
 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>