@snaptrude/plugin-core 0.3.0 → 0.5.0

package/src/api/entity/referenceLine.ts

@@ -1,7 +1,6 @@
 import * as z from "zod"
 import { PluginApiReturn } from "../../types"
-import { PProfile } from "../core/geom/profile"
-import { PCurve } from "../core/geom/curve"
+import { ProfileHandle, CurveHandle } from "../../handles"
 
 /**
  * Reference line management — create, query, and delete reference lines.
@@ -21,61 +20,68 @@ export abstract class PluginReferenceLineApi {
   /**
    * Create multiple reference lines from a profile.
    *
-   * Each {@linkcode PCurve} in the given {@linkcode PProfile} becomes
+   * Each curve in the given {@linkcode ProfileHandle} 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
+   * @param profile - A {@linkcode ProfileHandle} 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
    *
+   * @examplePrompt Draw grid lines across the site
+   * @examplePrompt Create reference lines from these curves
+   * @examplePrompt Add alignment guides along the building edge
+   * @examplePrompt Set up a structural grid using guide lines
+   * @examplePrompt Turn this profile into reference lines
+   *
    * # 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 start = await vec3.new(0, 0, 0)
+   * const mid = await vec3.new(10, 0, 0)
+   * const end = await vec3.new(10, 0, 10)
+   * const l1 = await snaptrude.core.geom.create.line(start, mid)
+   * const l2 = await snaptrude.core.geom.create.line(mid, end)
+   * const profile = await snaptrude.core.geom.create.profileFromCurves([l1, l2])
    *
-   * const { referenceLineIds } = await snaptrude.entity.referenceLine.createMulti({
-   *   profile,
-   * })
+   * const { referenceLineIds } = await snaptrude.entity.referenceLine.createMulti(profile)
    * ```
    */
   public abstract createMulti(
-    args: PluginReferenceLineCreateMultiArgs
+    profile: ProfileHandle
   ): 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.
+   * Only the properties listed in `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}.
+   * @param referenceLineId - The unique reference line ID
+   * @param 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
    *
+   * @examplePrompt Get the curve geometry of this reference line
+   * @examplePrompt Where does this grid line run?
+   * @examplePrompt Read the geometry of a guide line by its id
+   * @examplePrompt Look up the curve of the selected reference line
+   *
    * # Example
    * ```ts
-   * const result = await snaptrude.entity.referenceLine.get({
-   *   referenceLineId: "some-ref-line-id",
-   *   properties: ["curve"],
-   * })
-   * console.log(result.curve) // PCurve
+   * const result = await snaptrude.entity.referenceLine.get("some-ref-line-id", ["curve"])
+   * // result.curve is an opaque CurveHandle; a dedicated curve read API for its
+   * // coordinates is exposed separately via `snaptrude.core.geom.curve`.
    * ```
    */
   public abstract get(
-    args: PluginReferenceLineGetArgs
+    referenceLineId: string,
+    properties: z.infer<typeof PluginReferenceLineGetProperty>[]
   ): PluginApiReturn<PluginReferenceLineGetResult>
 
   /**
@@ -88,6 +94,11 @@ export abstract class PluginReferenceLineApi {
    * @returns A {@linkcode PluginReferenceLineGetAllResult} with a
    *   `referenceLineIds` array
    *
+   * @examplePrompt How many grid lines are in the project?
+   * @examplePrompt List all the reference lines in my model
+   * @examplePrompt Show every guide line in the file
+   * @examplePrompt Do I have any reference lines in this project?
+   *
    * # Example
    * ```ts
    * const { referenceLineIds } = await snaptrude.entity.referenceLine.getAll()
@@ -102,20 +113,21 @@ export abstract class PluginReferenceLineApi {
    * 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
+   * @param referenceLineId - The unique reference line ID to delete
    * @throws If the reference line does not exist
    *
+   * @examplePrompt Delete this reference line
+   * @examplePrompt Remove the grid line I just drew
+   * @examplePrompt Get rid of the alignment guide on the left
+   * @examplePrompt Erase a reference line by its id
+   *
    * # Example
    * ```ts
-   * await snaptrude.entity.referenceLine.delete({
-   *   referenceLineId: "some-ref-line-id",
-   * })
+   * await snaptrude.entity.referenceLine.delete("some-ref-line-id")
    * ```
    */
   public abstract delete(
-    args: PluginReferenceLineDeleteArgs
+    referenceLineId: string
   ): PluginApiReturn<PluginReferenceLineDeleteResult>
 }
 
@@ -124,10 +136,10 @@ export abstract class PluginReferenceLineApi {
  *
  * | Property | Type | Description |
  * |---|---|---|
- * | `profile` | {@linkcode PProfile} | Profile whose curves define reference lines |
+ * | `profile` | {@linkcode ProfileHandle} | Profile handle whose curves define reference lines |
  */
 export const PluginReferenceLineCreateMultiArgs = z.object({
-  profile: PProfile,
+  profile: ProfileHandle,
 })
 
 export type PluginReferenceLineCreateMultiArgs = z.infer<typeof PluginReferenceLineCreateMultiArgs>
@@ -150,7 +162,7 @@ export type PluginReferenceLineCreateMultiResult = z.infer<typeof PluginReferenc
  *
  * | Value | Return Type | Description |
  * |---|---|---|
- * | `"curve"` | {@linkcode PCurve} | The curve geometry of the reference line |
+ * | `"curve"` | {@linkcode CurveHandle} | The curve geometry of the reference line, as an opaque handle |
  */
 export const PluginReferenceLineGetProperty = z.enum([
   "curve",
@@ -179,7 +191,7 @@ export type PluginReferenceLineGetArgs = z.infer<typeof PluginReferenceLineGetAr
  */
 export const PluginReferenceLineGetResult = z
   .object({
-    curve: PCurve,
+    curve: CurveHandle,
   })
   .partial()