@snaptrude/plugin-core 0.3.0 → 0.5.0

package/src/api/core/project/index.ts

@@ -0,0 +1,418 @@
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+
+/**
+ * Project-level settings and info.
+ *
+ * Accessed via `snaptrude.core.project`. Currently exposes
+ * {@linkcode PluginProjectApi.settings} (snap + grid controls).
+ */
+export abstract class PluginProjectApi {
+  constructor() {}
+
+  /** Project settings — snaps and grid. See {@linkcode PluginProjectSettingsApi}. */
+  public abstract settings: PluginProjectSettingsApi
+}
+
+/**
+ * Project settings — tolerance, snaps, and grid.
+ *
+ * Accessed via `snaptrude.core.project.settings`.
+ */
+export abstract class PluginProjectSettingsApi {
+  constructor() {}
+
+  /**
+   * Get the project tolerance as a numeric magnitude.
+   *
+   * The engine stores tolerance as a discrete per-unit precision option; this
+   * returns its magnitude (decimal precision `"0.00"` → `0.01`; fraction `"1/4"`
+   * → `0.25`).
+   *
+   * @examplePrompt What is the tolerance setting in this project?
+   * @examplePrompt Check the current dimension precision of the model
+   * @examplePrompt How precise are the measurements in this project?
+   * @examplePrompt Show me the project's tolerance value
+   *
+   * # Example
+   * ```ts
+   * const tolerance = await snaptrude.core.project.settings.getTolerance()
+   * console.log(tolerance) // e.g. 0.01
+   * ```
+   */
+  public abstract getTolerance(): PluginApiReturn<number>
+
+  /**
+   * Set the project tolerance. The value snaps to the **nearest allowed**
+   * per-unit precision option (tolerance is a discrete dropdown, not arbitrary).
+   *
+   * @param value - Target tolerance magnitude; snaps to the nearest allowed option.
+   * @returns `true` once applied; `false` if no tolerance options are available.
+   *
+   * @examplePrompt Set the project tolerance to 0.01
+   * @examplePrompt Change the dimension precision to two decimal places
+   * @examplePrompt Round dimensions to the nearest quarter inch
+   * @examplePrompt Make the measurements in this project more precise
+   *
+   * # Example
+   * ```ts
+   * // snaps to the nearest allowed precision option
+   * const applied = await snaptrude.core.project.settings.setTolerance(0.01)
+   * if (!applied) console.log("no tolerance options available")
+   * ```
+   */
+  public abstract setTolerance(value: number): PluginApiReturn<boolean>
+
+  /** Snap controls (dimension / angle / parallel / normal / magnetic). See {@linkcode PluginSnapsApi}. */
+  public abstract snaps: PluginSnapsApi
+  /** Grid controls. See {@linkcode PluginGridApi}. */
+  public abstract grid: PluginGridApi
+}
+
+/**
+ * Snap controls. Dimension and angle snaps each have a numeric threshold plus an
+ * on/off toggle; parallel, normal, and magnetic snaps are on/off only.
+ * (`normal` is the perpendicular snap.)
+ *
+ * Accessed via `snaptrude.core.project.settings.snaps`.
+ */
+export abstract class PluginSnapsApi {
+  constructor() {}
+
+  /**
+   * Set the dimension-snap threshold — the length increment that drawing and
+   * editing snap to when dimension snapping is on.
+   *
+   * @param value - The snap threshold distance.
+   *
+   * @examplePrompt Set the dimension snap to 100mm
+   * @examplePrompt Change the snap distance to half a metre
+   * @examplePrompt Make the cursor snap every 6 inches when drawing
+   * @examplePrompt Adjust the snapping increment for lengths
+   *
+   * # Example
+   * ```ts
+   * // the threshold only applies while dimension snapping is on
+   * await snaptrude.core.project.settings.snaps.setDimension(100)
+   * await snaptrude.core.project.settings.snaps.enableDimension()
+   * ```
+   */
+  public abstract setDimension(value: number): PluginApiReturn<boolean>
+  /**
+   * Get the current dimension-snap threshold — the length increment that
+   * drawing and editing snap to when dimension snapping is on.
+   *
+   * @examplePrompt What is the dimension snap distance?
+   * @examplePrompt Check the current snap increment for drawing
+   * @examplePrompt How far apart are the length snaps set?
+   * @examplePrompt Show me the snap spacing value
+   *
+   * # Example
+   * ```ts
+   * const increment = await snaptrude.core.project.settings.snaps.getDimension()
+   * console.log(increment)
+   * ```
+   */
+  public abstract getDimension(): PluginApiReturn<number>
+  /**
+   * Turn dimension snapping on, so drawing and editing snap to the configured
+   * length increment.
+   *
+   * @examplePrompt Turn on dimension snapping
+   * @examplePrompt Enable snapping to set lengths while I draw
+   * @examplePrompt Make my walls snap to round dimensions
+   * @examplePrompt Switch length snapping back on
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.project.settings.snaps.enableDimension()
+   * ```
+   */
+  public abstract enableDimension(): PluginApiReturn<boolean>
+  /**
+   * Turn dimension snapping off, so lengths no longer snap to the configured
+   * increment while drawing.
+   *
+   * @examplePrompt Turn off dimension snapping
+   * @examplePrompt Stop snapping to fixed lengths when I draw
+   * @examplePrompt Disable the length snap so I can draw freely
+   * @examplePrompt I don't want dimensions to snap anymore
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.project.settings.snaps.disableDimension()
+   * ```
+   */
+  public abstract disableDimension(): PluginApiReturn<boolean>
+
+  /**
+   * Set the angle-snap threshold in degrees — the angular increment that
+   * drawing snaps to when angle snapping is on.
+   *
+   * @param value - The snap threshold in degrees.
+   *
+   * @examplePrompt Set the angle snap to 15 degrees
+   * @examplePrompt Change angle snapping to every 45 degrees
+   * @examplePrompt Make drawing snap at 30 degree increments
+   * @examplePrompt Adjust the rotation snap angle
+   *
+   * # Example
+   * ```ts
+   * // snap drawing to 15-degree increments (applies while angle snapping is on)
+   * await snaptrude.core.project.settings.snaps.setAngle(15)
+   * await snaptrude.core.project.settings.snaps.enableAngle()
+   * ```
+   */
+  public abstract setAngle(value: number): PluginApiReturn<boolean>
+  /**
+   * Get the current angle-snap threshold in degrees — the angular increment
+   * that drawing snaps to when angle snapping is on.
+   *
+   * @examplePrompt What angle does drawing snap to?
+   * @examplePrompt Check the current angle snap in degrees
+   * @examplePrompt Show me the angle snapping increment
+   * @examplePrompt How many degrees is the angle snap set to?
+   *
+   * # Example
+   * ```ts
+   * const degrees = await snaptrude.core.project.settings.snaps.getAngle()
+   * console.log(degrees)
+   * ```
+   */
+  public abstract getAngle(): PluginApiReturn<number>
+  /**
+   * Turn angle snapping on, so drawn lines snap to the configured angle
+   * increment.
+   *
+   * @examplePrompt Turn on angle snapping
+   * @examplePrompt Enable snapping to angles while drawing
+   * @examplePrompt Make my lines snap to set angles
+   * @examplePrompt Switch angle snap back on
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.project.settings.snaps.enableAngle()
+   * ```
+   */
+  public abstract enableAngle(): PluginApiReturn<boolean>
+  /**
+   * Turn angle snapping off, so lines can be drawn at any angle without
+   * snapping to fixed increments.
+   *
+   * @examplePrompt Turn off angle snapping
+   * @examplePrompt Stop lines snapping to fixed angles
+   * @examplePrompt Disable the angle snap so I can draw at any angle
+   * @examplePrompt Remove angle snapping while sketching
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.project.settings.snaps.disableAngle()
+   * ```
+   */
+  public abstract disableAngle(): PluginApiReturn<boolean>
+
+  /**
+   * Turn parallel snapping on, so drawing snaps when the cursor lines up
+   * parallel to existing edges.
+   *
+   * @examplePrompt Turn on parallel snapping
+   * @examplePrompt Enable snapping to parallel lines
+   * @examplePrompt Help me draw walls parallel to existing ones
+   * @examplePrompt Snap to parallel edges when drawing
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.project.settings.snaps.enableParallel()
+   * ```
+   */
+  public abstract enableParallel(): PluginApiReturn<boolean>
+  /**
+   * Turn parallel snapping off, so drawing no longer snaps to directions
+   * parallel to existing edges.
+   *
+   * @examplePrompt Turn off parallel snapping
+   * @examplePrompt Stop snapping to parallel edges
+   * @examplePrompt Disable the parallel snap guide
+   * @examplePrompt I don't want my lines snapping parallel anymore
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.project.settings.snaps.disableParallel()
+   * ```
+   */
+  public abstract disableParallel(): PluginApiReturn<boolean>
+
+  /**
+   * Turn normal (perpendicular) snapping on, so drawing snaps when the cursor
+   * is at a right angle to existing edges.
+   *
+   * @examplePrompt Turn on perpendicular snapping
+   * @examplePrompt Enable the normal snap so lines snap at right angles
+   * @examplePrompt Snap to perpendicular when I draw walls
+   * @examplePrompt Help me draw at 90 degrees to existing edges
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.project.settings.snaps.enableNormal()
+   * ```
+   */
+  public abstract enableNormal(): PluginApiReturn<boolean>
+  /**
+   * Turn normal (perpendicular) snapping off, so drawing no longer snaps at
+   * right angles to existing edges.
+   *
+   * @examplePrompt Turn off perpendicular snapping
+   * @examplePrompt Disable the normal snap
+   * @examplePrompt Stop snapping at right angles to edges
+   * @examplePrompt Remove the 90 degree snap guide
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.project.settings.snaps.disableNormal()
+   * ```
+   */
+  public abstract disableNormal(): PluginApiReturn<boolean>
+
+  /**
+   * Turn magnetic snapping on, so the cursor is pulled to nearby geometry
+   * while drawing.
+   *
+   * @examplePrompt Turn on magnetic snapping
+   * @examplePrompt Enable the magnet snap
+   * @examplePrompt Make the cursor stick to nearby geometry when drawing
+   * @examplePrompt Switch magnetic snap back on
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.project.settings.snaps.enableMagnetic()
+   * ```
+   */
+  public abstract enableMagnetic(): PluginApiReturn<boolean>
+  /**
+   * Turn magnetic snapping off, so the cursor is no longer pulled to nearby
+   * geometry while drawing.
+   *
+   * @examplePrompt Turn off magnetic snapping
+   * @examplePrompt Disable the magnet snap
+   * @examplePrompt Stop the cursor sticking to nearby objects
+   * @examplePrompt The magnetic snap is annoying, switch it off
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.project.settings.snaps.disableMagnetic()
+   * ```
+   */
+  public abstract disableMagnetic(): PluginApiReturn<boolean>
+}
+
+/**
+ * Grid controls — the visual snap-to grid.
+ *
+ * Accessed via `snaptrude.core.project.settings.grid`.
+ */
+export abstract class PluginGridApi {
+  constructor() {}
+
+  /**
+   * Turn the grid on, showing the visual snap-to grid in the canvas.
+   *
+   * @examplePrompt Turn on the grid
+   * @examplePrompt Show the grid in my project
+   * @examplePrompt Enable the drawing grid
+   * @examplePrompt Switch the snap grid back on
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.project.settings.grid.enable()
+   * ```
+   */
+  public abstract enable(): PluginApiReturn<boolean>
+  /**
+   * Turn the grid off, hiding the visual snap-to grid in the canvas.
+   *
+   * @examplePrompt Turn off the grid
+   * @examplePrompt Hide the grid
+   * @examplePrompt Disable the background grid in the canvas
+   * @examplePrompt Remove the drawing grid from view
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.project.settings.grid.disable()
+   * ```
+   */
+  public abstract disable(): PluginApiReturn<boolean>
+  /**
+   * Set the grid cell value — the size of each cell in the visual snap-to
+   * grid.
+   *
+   * @param value - The grid cell value.
+   *
+   * @examplePrompt Set the grid spacing to 1 metre
+   * @examplePrompt Change the grid cell size to 500mm
+   * @examplePrompt Make the grid squares 2 feet wide
+   * @examplePrompt Adjust the grid size in this project
+   *
+   * # Example
+   * ```ts
+   * await snaptrude.core.project.settings.grid.setValue(1)
+   * await snaptrude.core.project.settings.grid.enable()
+   * ```
+   */
+  public abstract setValue(value: number): PluginApiReturn<boolean>
+  /**
+   * Get the current grid cell value — the size of each cell in the visual
+   * snap-to grid.
+   *
+   * @examplePrompt What is the grid spacing?
+   * @examplePrompt Check the current grid cell size
+   * @examplePrompt How big are the grid squares?
+   * @examplePrompt Show me the grid size setting
+   *
+   * # Example
+   * ```ts
+   * const cellSize = await snaptrude.core.project.settings.grid.getValue()
+   * console.log(cellSize)
+   * ```
+   */
+  public abstract getValue(): PluginApiReturn<number>
+}
+
+/**
+ * Arguments for the snap-threshold setters
+ * ({@linkcode PluginSnapsApi.setDimension} / {@linkcode PluginSnapsApi.setAngle}).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `value` | `number` | The snap threshold (distance, or degrees for angle) |
+ */
+export const PluginSnapValueArgs = z.object({
+  value: z.number(),
+})
+
+export type PluginSnapValueArgs = z.infer<typeof PluginSnapValueArgs>
+
+/**
+ * Arguments for {@linkcode PluginGridApi.setValue}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `value` | `number` | The grid cell value |
+ */
+export const PluginGridValueArgs = z.object({
+  value: z.number(),
+})
+
+export type PluginGridValueArgs = z.infer<typeof PluginGridValueArgs>
+
+/**
+ * Arguments for {@linkcode PluginProjectSettingsApi.setTolerance}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `value` | `number` | Target tolerance magnitude; snaps to the nearest allowed option |
+ */
+export const PluginToleranceArgs = z.object({
+  value: z.number(),
+})
+
+export type PluginToleranceArgs = z.infer<typeof PluginToleranceArgs>