@snaptrude/plugin-core 0.9.16 → 0.9.18-edgesetbacks-20261021.1

package/src/api/design/grids.ts

@@ -1,237 +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>
-}
+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>
+}