@snaptrude/plugin-core 0.0.0-bimsvg-20260928124803

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

@@ -0,0 +1,319 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { ComponentHandle } from "../../../handles"
+import { PluginDesignChangeResult } from "../lock"
+import { PluginObjectCatalogGroup } from "../doors"
+
+/**
+ * `snaptrude.design.furniture` — the placeable furniture **catalog** (a library of
+ * source items, NOT scene entities) plus dimension reads/edits of PLACED furniture.
+ * Placement lives at `design.create.furniture` (returns a {@linkcode ComponentHandle});
+ * generic reads of placed furniture live at `design.query.listFurniture`/`getProperties`.
+ *
+ * Catalog items are plain value records ({@linkcode PluginFurnitureCatalogItem}) keyed
+ * by a library id (team `_id` or general `fullName`) — not handles. Reads are async
+ * (network-backed) but carry no `Async` suffix (§6.6).
+ *
+ * {@linkcode PluginDesignFurnitureApi.getDimensions} / {@linkcode PluginDesignFurnitureApi.setDimensions}
+ * target a PLACED furniture {@linkcode ComponentHandle} (not a catalog id) — `length`
+ * along the object, `width` across it, `height` up. Values are engine units, matching
+ * the length/width/height fields the furniture properties panel shows.
+ */
+export abstract class PluginDesignFurnitureApi {
+  constructor() {}
+
+  /**
+   * Get the dimensions of a PLACED furniture item — `length` (along the object),
+   * `width` (across it) and `height` (vertical), in engine units. Mirrors the
+   * Length/Width/Height fields of the furniture properties panel.
+   *
+   * @param item The placed furniture to query
+   * @returns The dimensions, or `null` if the geometry is degenerate
+   *
+   * @examplePrompt How big is this sofa?
+   * @examplePrompt What are the dimensions of the selected furniture?
+   * @examplePrompt Measure the length, width and height of this table
+   * @examplePrompt Get the size of the chair I just placed
+   *
+   * # Example
+   * ```ts
+   * const [item] = await snaptrude.design.query.listFurniture({ isSelected: true })
+   * const dims = await snaptrude.design.furniture.getDimensions(item)
+   * if (dims) console.log(dims.length, dims.width, dims.height)
+   * ```
+   */
+  public abstract getDimensions(
+    item: ComponentHandle
+  ): PluginApiReturn<PluginFurnitureDimensions | null>
+
+  /**
+   * Resize a PLACED furniture item along one or more axes — `length`, `width`
+   * and/or `height` (engine units). Omitted axes are left unchanged. Each supplied
+   * axis is an undoable command, mirroring editing the furniture properties panel.
+   *
+   * @param item The placed furniture to resize
+   * @param dimensions New `length` / `width` / `height` (each optional, engine units)
+   * @returns The affected furniture
+   *
+   * @examplePrompt Make this table 1.8m long
+   * @examplePrompt Resize the selected sofa to 2000 wide
+   * @examplePrompt Set this furniture to 800mm tall
+   * @examplePrompt Change the desk to 1500 long and 700 deep
+   *
+   * # Example
+   * ```ts
+   * const [item] = await snaptrude.design.query.listFurniture({ isSelected: true })
+   * const { affected } = await snaptrude.design.furniture.setDimensions(item, {
+   *   length: 1800,
+   *   height: 750
+   * })
+   * ```
+   */
+  public abstract setDimensions(
+    item: ComponentHandle,
+    dimensions: PluginFurnitureDimensionUpdates
+  ): PluginApiReturn<PluginDesignChangeResult>
+
+  /**
+   * List the categories (Living, Bedroom, Kitchen, …) that organize the
+   * furniture catalog — the picker taxonomy, merged from built-in categories,
+   * team types, and backend user types. Pass a value to
+   * {@linkcode PluginDesignFurnitureApi.listCatalog}'s `category` filter.
+   * @returns The category names (`[]` when empty)
+   *
+   * @examplePrompt What furniture categories are available?
+   * @examplePrompt List the furniture categories
+   * @examplePrompt Show me the furniture groups like living and bedroom
+   * @examplePrompt Which furniture categories can I filter by?
+   *
+   * # Example
+   * ```ts
+   * const categories = await snaptrude.design.furniture.listCategories()
+   * const [first] = categories
+   * const items = await snaptrude.design.furniture.listCatalog(undefined, first)
+   * console.log(first, "→", items.length, "items")
+   * ```
+   *
+   * @deprecated Use `design.furniture.listCatalogGroups` — the same name
+   * `design.doors` and `design.windows` use. Still supported.
+   */
+  public abstract listCategories(): PluginApiReturn<string[]>
+
+  /**
+   * List the furniture catalog's groups. Matches
+   * {@linkcode PluginDesignDoorsApi.listCatalogGroups} and
+   * {@linkcode PluginDesignWindowsApi.listCatalogGroups}, so all three catalog
+   * surfaces are named alike.
+   *
+   * `source` is `"default"` for the built-in picker groups and `"team"` for the
+   * sub-types of THIS project's team library — exactly the split
+   * {@linkcode PluginDesignFurnitureApi.listCatalog}'s `source` filter uses, so
+   * every `"team"` group is guaranteed to match at least one team item here.
+   * For furniture the group token and its label are the same string (the
+   * category), so `dbType === label`; `design.doors`/`design.windows` have a
+   * distinct engine `dbType`.
+   *
+   * @returns The catalog groups as {@linkcode PluginObjectCatalogGroup}`[]`
+   *   (`[]` when empty). Pass a group's `dbType` (=== `label`) to
+   *   {@linkcode PluginDesignFurnitureApi.listCatalog}'s `category` filter to
+   *   list its items.
+   *
+   * @examplePrompt What furniture groups are available?
+   * @examplePrompt List the furniture categories in this project
+   *
+   * # Example
+   * ```ts
+   * const groups = await snaptrude.design.furniture.listCatalogGroups()
+   * for (const g of groups) console.log(g.dbType, g.label, g.source)
+   * ```
+   */
+  public abstract listCatalogGroups(): PluginApiReturn<PluginObjectCatalogGroup[]>
+
+  /**
+   * List the placeable furniture catalog (team + general libraries),
+   * optionally filtered by library `source` and/or `category`.
+   * @param source Restrict to one library (optional)
+   * @param category Restrict to one category (optional; see {@linkcode PluginDesignFurnitureApi.listCategories})
+   * @returns The catalog as {@linkcode PluginFurnitureCatalogItem}`[]` (`[]` when empty)
+   *
+   * @examplePrompt What furniture can I place in this project?
+   * @examplePrompt Show me all the furniture available in the library
+   * @examplePrompt List the chairs and tables I can add to the model
+   * @examplePrompt Which furniture items are in my team's library?
+   * @examplePrompt Show me the bedroom furniture I can place
+   *
+   * # Example
+   * ```ts
+   * const bedroom = await snaptrude.design.furniture.listCatalog("team", "bedroom")
+   * for (const item of bedroom) console.log(item.id, item.name, item.thumbnailUrl)
+   * ```
+   */
+  public abstract listCatalog(
+    source?: "team" | "general",
+    category?: string
+  ): PluginApiReturn<PluginFurnitureCatalogItem[]>
+
+  /**
+   * Get a single 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 furniture item from the library
+   * @examplePrompt Look up the catalog entry for this chair id
+   * @examplePrompt What is the cost of this furniture item?
+   * @examplePrompt Show me the family name of the sofa in the catalog
+   *
+   * # Example
+   * ```ts
+   * const [entry] = await snaptrude.design.furniture.listCatalog()
+   * const item = await snaptrude.design.furniture.getCatalogItem(entry.id)
+   * if (item) console.log(item.name, item.source, item.familyName)
+   * ```
+   */
+  public abstract getCatalogItem(
+    id: string
+  ): PluginApiReturn<PluginFurnitureCatalogItem | null>
+
+  /**
+   * Test whether a catalog item exists for the given library id.
+   * @param id The catalog library id
+   * @returns `true` if it exists, otherwise `false`
+   *
+   * @examplePrompt Is this furniture item still in the library?
+   * @examplePrompt Check whether a catalog item with this id exists
+   * @examplePrompt Does my team library have this chair?
+   * @examplePrompt Verify the sofa is available in the catalog before placing it
+   *
+   * # Example
+   * ```ts
+   * const [entry] = await snaptrude.design.furniture.listCatalog()
+   * const stillAvailable = await snaptrude.design.furniture.exists(entry.id)
+   * console.log(stillAvailable ? "safe to place" : "removed from library")
+   * ```
+   */
+  public abstract exists(id: string): PluginApiReturn<boolean>
+}
+
+/**
+ * A placeable furniture catalog item (value record — not a scene entity/handle).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | Library id (team `_id` or general `fullName`) — pass to `design.create.furniture` |
+ * | `name` | `string` | Display name |
+ * | `source` | `'team' \| 'general'` | Which library it came from |
+ * | `subType` | `string` | Sub-type (optional) |
+ * | `category` | `string` | Category the item belongs to (optional) |
+ * | `thumbnailUrl` | `string` | Preview thumbnail URL (optional; never the mesh URL) |
+ * | `cost` | `number` | Cost (optional; team items) |
+ * | `familyName` | `string` | Family name (optional) |
+ */
+export const PluginFurnitureCatalogItem = z.object({
+  id: z.string(),
+  name: z.string(),
+  source: z.enum(["team", "general"]),
+  subType: z.string().optional(),
+  category: z.string().optional(),
+  thumbnailUrl: z.string().optional(),
+  cost: z.number().optional(),
+  familyName: z.string().optional(),
+})
+export type PluginFurnitureCatalogItem = z.infer<typeof PluginFurnitureCatalogItem>
+
+/**
+ * Arguments for {@linkcode PluginDesignFurnitureApi.listCatalog}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `source` | `'team' \| 'general'` | Restrict to one library (optional) |
+ * | `category` | `string` | Restrict to one category (optional) |
+ */
+export const PluginDesignFurnitureListCatalogArgs = z.object({
+  source: z.enum(["team", "general"]).optional(),
+  category: z.string().optional(),
+})
+export type PluginDesignFurnitureListCatalogArgs = z.infer<
+  typeof PluginDesignFurnitureListCatalogArgs
+>
+
+/**
+ * Arguments for {@linkcode PluginDesignFurnitureApi.getCatalogItem} / {@linkcode PluginDesignFurnitureApi.exists}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `id` | `string` | The catalog library id |
+ */
+export const PluginDesignFurnitureGetCatalogItemArgs = z.object({
+  id: z.string(),
+})
+export type PluginDesignFurnitureGetCatalogItemArgs = z.infer<
+  typeof PluginDesignFurnitureGetCatalogItemArgs
+>
+
+export const PluginDesignFurnitureExistsArgs = PluginDesignFurnitureGetCatalogItemArgs
+export type PluginDesignFurnitureExistsArgs = z.infer<typeof PluginDesignFurnitureExistsArgs>
+
+// ---------------------------------------------------------------------------
+// placed-furniture dimensions
+// ---------------------------------------------------------------------------
+
+/**
+ * A placed furniture item's dimensions (engine units).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `length` | `number` | Along the object (panel "Length") |
+ * | `width` | `number` | Across the object (panel "Width") |
+ * | `height` | `number` | Vertical (panel "Height") |
+ */
+export const PluginFurnitureDimensions = z.object({
+  length: z.number(),
+  width: z.number(),
+  height: z.number(),
+})
+export type PluginFurnitureDimensions = z.infer<typeof PluginFurnitureDimensions>
+
+/**
+ * Arguments for {@linkcode PluginDesignFurnitureApi.getDimensions}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `item` | {@linkcode ComponentHandle} | The placed furniture to query |
+ */
+export const PluginDesignFurnitureItemArgs = z.object({
+  item: ComponentHandle,
+})
+export type PluginDesignFurnitureItemArgs = z.infer<typeof PluginDesignFurnitureItemArgs>
+
+/**
+ * A partial dimension patch — each axis is optional; omitted axes are unchanged.
+ * Every supplied axis must be a positive engine-unit length.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `length` | `number`? | New length along the object (engine units, > 0) |
+ * | `width` | `number`? | New width across the object (engine units, > 0) |
+ * | `height` | `number`? | New height (engine units, > 0) |
+ */
+export const PluginFurnitureDimensionUpdates = z.object({
+  length: z.number().positive().optional(),
+  width: z.number().positive().optional(),
+  height: z.number().positive().optional(),
+})
+export type PluginFurnitureDimensionUpdates = z.infer<typeof PluginFurnitureDimensionUpdates>
+
+/**
+ * Arguments for {@linkcode PluginDesignFurnitureApi.setDimensions}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `item` | {@linkcode ComponentHandle} | The placed furniture to resize |
+ * | `dimensions` | {@linkcode PluginFurnitureDimensionUpdates} | The axes to change (each optional) |
+ */
+export const PluginDesignFurnitureSetDimensionsArgs = z.object({
+  item: ComponentHandle,
+  dimensions: PluginFurnitureDimensionUpdates,
+})
+export type PluginDesignFurnitureSetDimensionsArgs = z.infer<
+  typeof PluginDesignFurnitureSetDimensionsArgs
+>

package/src/api/design/grids.ts

@@ -0,0 +1,237 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { ComponentHandle } from "../../handles"
+import { PluginGridStyleOptions } from "./create/grids"
+
+/**
+ * Tag policy for structural line removal (mirrors the engine
+ * `GridLineTagPolicy` values verbatim): `"rewrite"` renumbers each affected
+ * wing's tag sequence after removal; `"preserve"` keeps the surviving lines'
+ * tags unchanged.
+ */
+export const PluginGridLineTagPolicy = z.enum(["rewrite", "preserve"])
+export type PluginGridLineTagPolicy = z.infer<typeof PluginGridLineTagPolicy>
+
+/** A positional grid-line address — indices into `design.query.grids.get`'s `wings` arrays. */
+export const PluginGridLineAddress = z.object({
+  wing: z.number().int().nonnegative(),
+  line: z.number().int().nonnegative(),
+})
+export type PluginGridLineAddress = z.infer<typeof PluginGridLineAddress>
+
+/**
+ * One per-wing entry of {@linkcode PluginDesignGridsApi.updateWings} —
+ * addressed by wing index. `spanMin`/`spanMax` move the family's length
+ * handles (Snaptrude units).
+ */
+export const PluginGridWingEntry = z.object({
+  wing: z.number().int().nonnegative(),
+  spacing: z.number().positive().finite().optional(),
+  count: z.number().int().min(1).optional(),
+  spanMin: z.number().finite().optional(),
+  spanMax: z.number().finite().optional(),
+})
+export type PluginGridWingEntry = z.infer<typeof PluginGridWingEntry>
+
+/** Arguments for {@linkcode PluginDesignGridsApi.updateWings}. */
+export const PluginDesignGridsUpdateWingsArgs = z.object({
+  grid: ComponentHandle,
+  wings: z.array(PluginGridWingEntry).min(1),
+})
+export type PluginDesignGridsUpdateWingsArgs = z.infer<
+  typeof PluginDesignGridsUpdateWingsArgs
+>
+
+/**
+ * One per-line entry of {@linkcode PluginDesignGridsApi.updateLines} —
+ * addressed positionally by `{ wing, line }` indices (invalidated by
+ * structural edits; re-query after mutating). `distanceToPrevious` /
+ * `distanceToNext` set the typed distance to the adjacent line on that side
+ * and are mutually exclusive.
+ *
+ * `visible` is **hide-only** (`false`), mirroring the product: per-line show
+ * does not exist — showing the GROUP (`design.visibility.show`) restores all
+ * of its lines, exactly like the native Show All.
+ */
+export const PluginGridLineEntry = z
+  .object({
+    wing: z.number().int().nonnegative(),
+    line: z.number().int().nonnegative(),
+    tag: z.string().min(1).optional(),
+    distanceToPrevious: z.number().positive().finite().optional(),
+    distanceToNext: z.number().positive().finite().optional(),
+    props: PluginGridStyleOptions.optional(),
+    visible: z.literal(false).optional(),
+  })
+  .superRefine((entry, ctx) => {
+    if (entry.distanceToPrevious !== undefined && entry.distanceToNext !== undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          "distanceToPrevious and distanceToNext are mutually exclusive on one line entry",
+      })
+    }
+  })
+export type PluginGridLineEntry = z.infer<typeof PluginGridLineEntry>
+
+/** Arguments for {@linkcode PluginDesignGridsApi.updateLines}. */
+export const PluginDesignGridsUpdateLinesArgs = z.object({
+  grid: ComponentHandle,
+  lines: z.array(PluginGridLineEntry).min(1),
+})
+export type PluginDesignGridsUpdateLinesArgs = z.infer<
+  typeof PluginDesignGridsUpdateLinesArgs
+>
+
+/** Arguments for {@linkcode PluginDesignGridsApi.addLine}. */
+export const PluginDesignGridsAddLineArgs = z.object({
+  grid: ComponentHandle,
+  wing: z.number().int().nonnegative(),
+  position: z.number().finite(),
+})
+export type PluginDesignGridsAddLineArgs = z.infer<typeof PluginDesignGridsAddLineArgs>
+
+/** Arguments for {@linkcode PluginDesignGridsApi.removeLines}. */
+export const PluginDesignGridsRemoveLinesArgs = z.object({
+  grid: ComponentHandle,
+  lines: z.array(PluginGridLineAddress).min(1),
+  tagPolicy: PluginGridLineTagPolicy.optional(),
+})
+export type PluginDesignGridsRemoveLinesArgs = z.infer<
+  typeof PluginDesignGridsRemoveLinesArgs
+>
+
+/**
+ * `design.grids.*` — structural edits on a grid's line structure (the
+ * entity-family home for grid-specific operations, like `design.doors`).
+ *
+ * Lines are addressed positionally as `{ wing, line }` index pairs into the
+ * `wings` arrays returned by `design.query.grids.get`. Adding, removing, or
+ * re-counting lines re-indexes the wing — re-query after every structural edit.
+ *
+ * Group-level edits (default styling, angle, storey visibility) live on
+ * `design.update.grid`; creation lives on `design.create.grid*`.
+ *
+ * Accessed via `snaptrude.design.grids`.
+ */
+export abstract class PluginDesignGridsApi {
+  constructor() {}
+
+  /**
+   * Update one or more **wings** of a grid with sparse per-wing entries —
+   * `spacing` (uniform re-space), `count` (grow/truncate + tag renumber),
+   * `spanMin`/`spanMax` (family length handles). Every change routes through
+   * the exact setters the native panel uses — each changed field commits its
+   * own undoable command, identical to editing that field in the panel.
+   *
+   * A `count` change re-indexes the wing's lines — positional `{ wing, line }`
+   * addresses held from before the call are stale afterwards; re-query.
+   *
+   * @param grid - The grid group
+   * @param wings - Sparse {@linkcode PluginGridWingEntry} entries (≥ 1)
+   * @returns `true` once applied
+   *
+   * @examplePrompt Change this grid's spacing to 8 metres
+   * @examplePrompt Make this grid 10 by 12 lines
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.design.grids.updateWings(grid, [{ wing: 0, spacing: 8, count: 10 }])
+   * ```
+   */
+  public abstract updateWings(
+    grid: ComponentHandle,
+    wings: PluginGridWingEntry[],
+  ): PluginApiReturn<boolean>
+
+  /**
+   * Update one or more **lines** of a grid with sparse per-line entries —
+   * `tag`, `distanceToPrevious`/`distanceToNext` (typed distance to the
+   * neighbour on that side; mutually exclusive), `props` (per-line style
+   * overrides), and `visible: false` (hide). Every change routes through the
+   * exact setters the native panel uses — each changed field commits its own
+   * undoable command, identical to editing that field in the panel.
+   *
+   * Visibility mirrors the product exactly: `visible` accepts only `false` —
+   * per-line show does not exist. Hiding lines that would leave NO visible
+   * line hides the whole GROUP instead (the native last-line rule; those line
+   * flags stay untouched). To bring hidden lines back, show the group
+   * (`design.visibility.show([grid])`) — it restores ALL of its lines, like
+   * the native Show All.
+   *
+   * @param grid - The grid group
+   * @param lines - Sparse {@linkcode PluginGridLineEntry} entries (≥ 1)
+   * @returns `true` once applied
+   *
+   * @examplePrompt Rename grid line 2 to "B"
+   * @examplePrompt Move this grid line 4 metres from its neighbour
+   * @examplePrompt Hide grid line 3 on this grid
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.design.grids.updateLines(grid, [
+   *   { wing: 0, line: 1, tag: "B", distanceToPrevious: 4 },
+   * ])
+   * ```
+   */
+  public abstract updateLines(
+    grid: ComponentHandle,
+    lines: PluginGridLineEntry[],
+  ): PluginApiReturn<boolean>
+
+  /**
+   * Insert a parallel grid line into a wing at an explicit position along the
+   * wing's spacing axis (Snaptrude units, wing-local — line 0's position can
+   * be read from its curve). Sibling lines do not shift; the wing's tag
+   * sequence is renumbered. Undoable.
+   *
+   * @param grid - The grid group
+   * @param wing - Wing index
+   * @param position - Position along the wing's spacing axis (Snaptrude units)
+   * @returns `true` once inserted
+   * @throws `VALIDATION` on a bad wing index or non-finite position
+   *
+   * @examplePrompt Add a grid line between lines 2 and 3
+   * @examplePrompt Insert an extra grid line 4 metres from line A
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.design.grids.addLine(grid, 0, 12.5)
+   * ```
+   */
+  public abstract addLine(
+    grid: ComponentHandle,
+    wing: number,
+    position: number,
+  ): PluginApiReturn<boolean>
+
+  /**
+   * Remove grid lines by positional address, as ONE undoable step. With
+   * `tagPolicy: "rewrite"` (default) each affected wing renumbers its tag
+   * sequence; `"preserve"` keeps surviving tags unchanged. A wing emptied of
+   * lines is dropped from the group.
+   *
+   * Removing EVERY line of the group is rejected — delete the group instead
+   * (`design.delete.entities`).
+   *
+   * @param grid - The grid group
+   * @param lines - Positional addresses to remove (see `design.query.grids.get`)
+   * @param tagPolicy - `"rewrite"` (default) or `"preserve"`
+   * @returns `true` once removed
+   * @throws `VALIDATION` on out-of-range addresses; `OPERATION_FAILED` when the
+   *   removal would delete the group's last line
+   *
+   * @examplePrompt Delete grid line B
+   * @examplePrompt Remove the last two lines of this grid without renumbering
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.design.grids.removeLines(grid, [{ wing: 0, line: 2 }], "preserve")
+   * ```
+   */
+  public abstract removeLines(
+    grid: ComponentHandle,
+    lines: PluginGridLineAddress[],
+    tagPolicy?: PluginGridLineTagPolicy,
+  ): PluginApiReturn<boolean>
+}