@snaptrude/plugin-core 0.0.5 → 0.0.7

package/src/api/entity/referenceLine.ts

@@ -0,0 +1,215 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../types"
+import { PProfile } from "../core/geom/profile"
+import { PCurve } from "../core/geom/curve"
+
+/**
+ * Reference line management — create, query, and delete reference lines.
+ *
+ * A **reference line** is a 2D guide line (or arc) in the Snaptrude scene,
+ * typically used for grid lines and alignment guides. Reference lines
+ * carry properties such as grid tags, labels, and line styles.
+ *
+ * All methods are **host API calls** that return Promises and support
+ * undo/redo via Snaptrude's command system.
+ *
+ * Accessed via `snaptrude.entity.referenceLine`.
+ */
+export abstract class PluginReferenceLineApi {
+  constructor() {}
+
+  /**
+   * Create multiple reference lines from a profile.
+   *
+   * Each {@linkcode PCurve} in the given {@linkcode PProfile} becomes
+   * a separate reference line. Uses `ReferenceLineConstructor.createFromProfile`
+   * internally.
+   *
+   * @param args - An object containing:
+   *   - {@linkcode PluginReferenceLineCreateMultiArgs.profile args.profile} — A
+   *     {@linkcode PProfile} whose curves define the reference lines to create
+   * @returns A {@linkcode PluginReferenceLineCreateMultiResult} with the
+   *   `referenceLineIds` of the created reference lines
+   * @throws If reference line creation fails
+   *
+   * # Example
+   * ```ts
+   * const { vec3 } = snaptrude.core.math
+   *
+   * const l1 = snaptrude.core.geom.line.new(vec3.new(0, 0, 0), vec3.new(10, 0, 0))
+   * const l2 = snaptrude.core.geom.line.new(vec3.new(10, 0, 0), vec3.new(10, 0, 10))
+   * const profile = snaptrude.core.geom.profile.new([l1, l2])
+   *
+   * const { referenceLineIds } = await snaptrude.entity.referenceLine.createMulti({
+   *   profile,
+   * })
+   * ```
+   */
+  public abstract createMulti(
+    args: PluginReferenceLineCreateMultiArgs
+  ): PluginApiReturn<PluginReferenceLineCreateMultiResult>
+
+  /**
+   * Get properties of a reference line by its ID.
+   *
+   * Only the properties listed in {@linkcode PluginReferenceLineGetArgs.properties
+   * args.properties} are returned — unlisted properties will be `undefined`
+   * in the result.
+   *
+   * @param args - An object containing:
+   *   - {@linkcode PluginReferenceLineGetArgs.referenceLineId args.referenceLineId} —
+   *     The unique reference line ID
+   *   - {@linkcode PluginReferenceLineGetArgs.properties args.properties} — Array of
+   *     property names to retrieve. See {@linkcode PluginReferenceLineGetProperty}.
+   * @returns A partial {@linkcode PluginReferenceLineGetResult} containing only the
+   *   requested properties
+   * @throws If the reference line does not exist
+   *
+   * # Example
+   * ```ts
+   * const result = await snaptrude.entity.referenceLine.get({
+   *   referenceLineId: "some-ref-line-id",
+   *   properties: ["curve"],
+   * })
+   * console.log(result.curve) // PCurve
+   * ```
+   */
+  public abstract get(
+    args: PluginReferenceLineGetArgs
+  ): PluginApiReturn<PluginReferenceLineGetResult>
+
+  /**
+   * Get the IDs of all reference lines in the current project.
+   *
+   * Returns every reference line across all stories.
+   * Use the returned IDs with {@linkcode PluginReferenceLineApi.get} to query
+   * individual reference line properties.
+   *
+   * @returns A {@linkcode PluginReferenceLineGetAllResult} with a
+   *   `referenceLineIds` array
+   *
+   * # Example
+   * ```ts
+   * const { referenceLineIds } = await snaptrude.entity.referenceLine.getAll()
+   * console.log(`Project has ${referenceLineIds.length} reference lines`)
+   * ```
+   */
+  public abstract getAll(): PluginApiReturn<PluginReferenceLineGetAllResult>
+
+  /**
+   * Delete a reference line by its ID.
+   *
+   * Permanently removes the reference line and its associated mesh from
+   * the scene. This operation is undoable via Snaptrude's command system.
+   *
+   * @param args - An object containing:
+   *   - {@linkcode PluginReferenceLineDeleteArgs.referenceLineId args.referenceLineId} —
+   *     The unique reference line ID to delete
+   * @throws If the reference line does not exist
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.entity.referenceLine.delete({
+   *   referenceLineId: "some-ref-line-id",
+   * })
+   * ```
+   */
+  public abstract delete(
+    args: PluginReferenceLineDeleteArgs
+  ): PluginApiReturn<PluginReferenceLineDeleteResult>
+}
+
+/**
+ * Arguments for {@linkcode PluginReferenceLineApi.createMulti}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `profile` | {@linkcode PProfile} | Profile whose curves define reference lines |
+ */
+export const PluginReferenceLineCreateMultiArgs = z.object({
+  profile: PProfile,
+})
+
+export type PluginReferenceLineCreateMultiArgs = z.infer<typeof PluginReferenceLineCreateMultiArgs>
+
+/**
+ * Result of {@linkcode PluginReferenceLineApi.createMulti}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `referenceLineIds` | `string[]` | IDs of the created reference lines |
+ */
+export const PluginReferenceLineCreateMultiResult = z.object({
+  referenceLineIds: z.array(z.string()),
+})
+
+export type PluginReferenceLineCreateMultiResult = z.infer<typeof PluginReferenceLineCreateMultiResult>
+
+/**
+ * Available properties that can be queried on a reference line.
+ *
+ * | Value | Return Type | Description |
+ * |---|---|---|
+ * | `"curve"` | {@linkcode PCurve} | The curve geometry of the reference line |
+ */
+export const PluginReferenceLineGetProperty = z.enum([
+  "curve",
+])
+
+/**
+ * Arguments for {@linkcode PluginReferenceLineApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `referenceLineId` | `string` | The reference line ID to query |
+ * | `properties` | {@linkcode PluginReferenceLineGetProperty}`[]` | Properties to retrieve |
+ */
+export const PluginReferenceLineGetArgs = z.object({
+  referenceLineId: z.string(),
+  properties: z.array(PluginReferenceLineGetProperty),
+})
+
+export type PluginReferenceLineGetArgs = z.infer<typeof PluginReferenceLineGetArgs>
+
+/**
+ * Result of {@linkcode PluginReferenceLineApi.get}.
+ *
+ * A partial object — only the properties that were requested in
+ * {@linkcode PluginReferenceLineGetArgs.properties} will be present.
+ */
+export const PluginReferenceLineGetResult = z
+  .object({
+    curve: PCurve,
+  })
+  .partial()
+
+export type PluginReferenceLineGetResult = z.infer<typeof PluginReferenceLineGetResult>
+
+/**
+ * Result of {@linkcode PluginReferenceLineApi.getAll}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `referenceLineIds` | `string[]` | IDs of all reference lines in the project |
+ */
+export const PluginReferenceLineGetAllResult = z.object({
+  referenceLineIds: z.array(z.string()),
+})
+
+export type PluginReferenceLineGetAllResult = z.infer<typeof PluginReferenceLineGetAllResult>
+
+/**
+ * Arguments for {@linkcode PluginReferenceLineApi.delete}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `referenceLineId` | `string` | The reference line ID to delete |
+ */
+export const PluginReferenceLineDeleteArgs = z.object({
+  referenceLineId: z.string(),
+})
+
+export type PluginReferenceLineDeleteArgs = z.infer<typeof PluginReferenceLineDeleteArgs>
+
+/** Result type for {@linkcode PluginReferenceLineApi.delete} — returns nothing on success. */
+export type PluginReferenceLineDeleteResult = void