@snaptrude/plugin-core 0.9.16 → 0.9.18-networks-20261016.1

package/src/api/design/query/grids.ts

@@ -1,197 +1,197 @@
-import * as z from "zod"
-import { PluginApiReturn } from "../../../types"
-import { CurveHandle, BBoxComponents } from "../../../handles"
-import { PluginReferenceLineStyle } from "../create"
-
-// ---------------------------------------------------------------------------
-// Records
-// ---------------------------------------------------------------------------
-
-/**
- * Visual properties of grid lines — the group's defaults and any per-line
- * overrides share this shape (values mirror the engine's `GridLineProps`).
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `style` | {@linkcode PluginReferenceLineStyle} | Line style (`"SOLID"` \| `"DASHED"` \| `"DOT_DASH"`) |
- * | `weight` | `number` | Line weight |
- * | `color` | `string` | Line color as a `#rrggbb` hex string |
- * | `showStart` | `boolean` | Whether the start-end tag bubble is shown |
- * | `showEnd` | `boolean` | Whether the end-end tag bubble is shown |
- */
-export const PluginGridLineProps = z.object({
-  style: PluginReferenceLineStyle,
-  weight: z.number(),
-  color: z.string(),
-  showStart: z.boolean(),
-  showEnd: z.boolean(),
-})
-export type PluginGridLineProps = z.infer<typeof PluginGridLineProps>
-
-/**
- * One grid line within a wing.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `curve` | {@linkcode CurveHandle} | The line's geometry in **world space** (a line or arc; read coordinates via `core.geom.curve`) |
- * | `tag` | `string` | The line's grid tag (e.g. `"A"`, `"3"`) |
- * | `visible` | `boolean` | Persisted per-line visibility |
- * | `props` | {@linkcode PluginGridLineProps} | **Effective** visual properties (group defaults merged with this line's overrides) |
- * | `overrides` | `Partial<`{@linkcode PluginGridLineProps}`>`? | This line's raw overrides, when any exist |
- */
-export const PluginGridLineRecord = z.object({
-  curve: CurveHandle,
-  tag: z.string(),
-  visible: z.boolean(),
-  props: PluginGridLineProps,
-  overrides: PluginGridLineProps.partial().optional(),
-})
-export type PluginGridLineRecord = z.infer<typeof PluginGridLineRecord>
-
-/**
- * One wing of a grid — a family of parallel lines sharing a local frame.
- * `spacing` and `span` are measured along the wing's local axes in
- * Snaptrude units; line addresses used by mutating APIs are
- * `{ wing, line }` index pairs into these arrays.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `spacing` | `number` | Nominal spacing between adjacent lines (Snaptrude units) |
- * | `tagStart` | `string` | First tag of the wing's deterministic tag sequence |
- * | `span` | `{ min: number; max: number }`? | Explicit family length along the wing's line axis, when baked |
- * | `lines` | {@linkcode PluginGridLineRecord}`[]` | The wing's lines, in wing order (index = the `line` address) |
- */
-export const PluginGridWingRecord = z.object({
-  spacing: z.number(),
-  tagStart: z.string(),
-  span: z.object({ min: z.number(), max: z.number() }).optional(),
-  lines: z.array(PluginGridLineRecord),
-})
-export type PluginGridWingRecord = z.infer<typeof PluginGridWingRecord>
-
-/**
- * Per-storey 2D-plan visibility of a grid.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `activeStorey` | `number` | The storey the grid belongs to |
- * | `disabledOnStoreys` | `number[]` | Storeys on whose 2D plan the grid is hidden |
- */
-export const PluginGridStoreyVisibility = z.object({
-  activeStorey: z.number(),
-  disabledOnStoreys: z.array(z.number()),
-})
-export type PluginGridStoreyVisibility = z.infer<typeof PluginGridStoreyVisibility>
-
-// ---------------------------------------------------------------------------
-// get — args & result
-// ---------------------------------------------------------------------------
-
-/**
- * Property names readable via {@linkcode PluginDesignQueryGridsApi.get}.
- *
- * | Value | Description |
- * |---|---|
- * | `"angle"` | World rotation about +Y, in **degrees** |
- * | `"props"` | Group-level default line properties |
- * | `"storeyVisibility"` | Active storey + storeys where the grid is hidden in 2D |
- * | `"wings"` | Full wing/line structure with world-space curve handles |
- * | `"bounds"` | World-space axis-aligned bounding box of the grid geometry |
- */
-export const PluginGridGetProperty = z.enum([
-  "angle",
-  "props",
-  "storeyVisibility",
-  "wings",
-  "bounds",
-])
-export type PluginGridGetProperty = z.infer<typeof PluginGridGetProperty>
-
-/**
- * Arguments for {@linkcode PluginDesignQueryGridsApi.get}.
- *
- * | Property | Type | Description |
- * |---|---|---|
- * | `gridId` | `string` | The grid group ID to query |
- * | `properties` | {@linkcode PluginGridGetProperty}`[]` | Properties to retrieve |
- */
-export const PluginGridGetArgs = z.object({
-  gridId: z.string(),
-  properties: z.array(PluginGridGetProperty),
-})
-export type PluginGridGetArgs = z.infer<typeof PluginGridGetArgs>
-
-/**
- * Result of {@linkcode PluginDesignQueryGridsApi.get} — only the requested
- * properties are present.
- */
-export const PluginGridGetResult = z
-  .object({
-    angle: z.number(),
-    props: PluginGridLineProps,
-    storeyVisibility: PluginGridStoreyVisibility,
-    wings: z.array(PluginGridWingRecord),
-    bounds: BBoxComponents,
-  })
-  .partial()
-export type PluginGridGetResult = z.infer<typeof PluginGridGetResult>
-
-// ---------------------------------------------------------------------------
-// Abstract API
-// ---------------------------------------------------------------------------
-
-/**
- * `design.query.grids.*` — structural-grid-specific reads.
- *
- * A **grid** (grid group) is a structural/documentation grid: one or more
- * *wings* (families of parallel lines with a shared local frame), each holding
- * tagged grid *lines* (straight lines, or a lone arc). Enumerate grids with
- * `design.query.listGrids`; read an individual grid's structure here.
- *
- * Lines have no stable identity of their own — mutating APIs address them
- * positionally as `{ wing, line }` index pairs into the `wings` arrays
- * returned by {@linkcode get}. Structural edits (adding/removing lines,
- * count changes) re-index lines; re-query after mutating.
- *
- * Accessed via `snaptrude.design.query.grids`.
- */
-export abstract class PluginDesignQueryGridsApi {
-  constructor() {}
-
-  /**
-   * Get properties of a grid by its ID.
-   *
-   * Only the properties listed in `properties` are returned — unlisted
-   * properties will be `undefined` in the result. `wings` is the heavy
-   * read (it registers a world-space {@linkcode CurveHandle} per line);
-   * request it only when the geometry is needed.
-   *
-   * Units: `angle` is in **degrees** (positive = CCW about +Y); `spacing`,
-   * `span`, `bounds`, and curve coordinates are in **Snaptrude units**,
-   * world space.
-   *
-   * @param gridId - The unique grid group ID
-   * @param properties - Array of property names to retrieve. See
-   *   {@linkcode PluginGridGetProperty}.
-   * @returns A partial {@linkcode PluginGridGetResult} containing only the
-   *   requested properties
-   * @throws If the grid does not exist
-   *
-   * @examplePrompt What is the spacing of this grid?
-   * @examplePrompt Read the grid line tags on this structural grid
-   * @examplePrompt Get the geometry of every line in this grid
-   * @examplePrompt Which storeys is this grid hidden on?
-   *
-   * # Example
-   * ```ts
-   * const [grid] = await snaptrude.design.query.listGrids()
-   * const { wings } = await snaptrude.design.query.grids.get(grid, ["wings"])
-   * // wings[0].lines[0].curve is an opaque CurveHandle in world space;
-   * // read its coordinates via `snaptrude.core.geom.curve`.
-   * ```
-   */
-  public abstract get(
-    gridId: string,
-    properties: z.infer<typeof PluginGridGetProperty>[],
-  ): PluginApiReturn<PluginGridGetResult>
-}
+import * as z from "zod"
+import { PluginApiReturn } from "../../../types"
+import { CurveHandle, BBoxComponents } from "../../../handles"
+import { PluginReferenceLineStyle } from "../create"
+
+// ---------------------------------------------------------------------------
+// Records
+// ---------------------------------------------------------------------------
+
+/**
+ * Visual properties of grid lines — the group's defaults and any per-line
+ * overrides share this shape (values mirror the engine's `GridLineProps`).
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `style` | {@linkcode PluginReferenceLineStyle} | Line style (`"SOLID"` \| `"DASHED"` \| `"DOT_DASH"`) |
+ * | `weight` | `number` | Line weight |
+ * | `color` | `string` | Line color as a `#rrggbb` hex string |
+ * | `showStart` | `boolean` | Whether the start-end tag bubble is shown |
+ * | `showEnd` | `boolean` | Whether the end-end tag bubble is shown |
+ */
+export const PluginGridLineProps = z.object({
+  style: PluginReferenceLineStyle,
+  weight: z.number(),
+  color: z.string(),
+  showStart: z.boolean(),
+  showEnd: z.boolean(),
+})
+export type PluginGridLineProps = z.infer<typeof PluginGridLineProps>
+
+/**
+ * One grid line within a wing.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `curve` | {@linkcode CurveHandle} | The line's geometry in **world space** (a line or arc; read coordinates via `core.geom.curve`) |
+ * | `tag` | `string` | The line's grid tag (e.g. `"A"`, `"3"`) |
+ * | `visible` | `boolean` | Persisted per-line visibility |
+ * | `props` | {@linkcode PluginGridLineProps} | **Effective** visual properties (group defaults merged with this line's overrides) |
+ * | `overrides` | `Partial<`{@linkcode PluginGridLineProps}`>`? | This line's raw overrides, when any exist |
+ */
+export const PluginGridLineRecord = z.object({
+  curve: CurveHandle,
+  tag: z.string(),
+  visible: z.boolean(),
+  props: PluginGridLineProps,
+  overrides: PluginGridLineProps.partial().optional(),
+})
+export type PluginGridLineRecord = z.infer<typeof PluginGridLineRecord>
+
+/**
+ * One wing of a grid — a family of parallel lines sharing a local frame.
+ * `spacing` and `span` are measured along the wing's local axes in
+ * Snaptrude units; line addresses used by mutating APIs are
+ * `{ wing, line }` index pairs into these arrays.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `spacing` | `number` | Nominal spacing between adjacent lines (Snaptrude units) |
+ * | `tagStart` | `string` | First tag of the wing's deterministic tag sequence |
+ * | `span` | `{ min: number; max: number }`? | Explicit family length along the wing's line axis, when baked |
+ * | `lines` | {@linkcode PluginGridLineRecord}`[]` | The wing's lines, in wing order (index = the `line` address) |
+ */
+export const PluginGridWingRecord = z.object({
+  spacing: z.number(),
+  tagStart: z.string(),
+  span: z.object({ min: z.number(), max: z.number() }).optional(),
+  lines: z.array(PluginGridLineRecord),
+})
+export type PluginGridWingRecord = z.infer<typeof PluginGridWingRecord>
+
+/**
+ * Per-storey 2D-plan visibility of a grid.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `activeStorey` | `number` | The storey the grid belongs to |
+ * | `disabledOnStoreys` | `number[]` | Storeys on whose 2D plan the grid is hidden |
+ */
+export const PluginGridStoreyVisibility = z.object({
+  activeStorey: z.number(),
+  disabledOnStoreys: z.array(z.number()),
+})
+export type PluginGridStoreyVisibility = z.infer<typeof PluginGridStoreyVisibility>
+
+// ---------------------------------------------------------------------------
+// get — args & result
+// ---------------------------------------------------------------------------
+
+/**
+ * Property names readable via {@linkcode PluginDesignQueryGridsApi.get}.
+ *
+ * | Value | Description |
+ * |---|---|
+ * | `"angle"` | World rotation about +Y, in **degrees** |
+ * | `"props"` | Group-level default line properties |
+ * | `"storeyVisibility"` | Active storey + storeys where the grid is hidden in 2D |
+ * | `"wings"` | Full wing/line structure with world-space curve handles |
+ * | `"bounds"` | World-space axis-aligned bounding box of the grid geometry |
+ */
+export const PluginGridGetProperty = z.enum([
+  "angle",
+  "props",
+  "storeyVisibility",
+  "wings",
+  "bounds",
+])
+export type PluginGridGetProperty = z.infer<typeof PluginGridGetProperty>
+
+/**
+ * Arguments for {@linkcode PluginDesignQueryGridsApi.get}.
+ *
+ * | Property | Type | Description |
+ * |---|---|---|
+ * | `gridId` | `string` | The grid group ID to query |
+ * | `properties` | {@linkcode PluginGridGetProperty}`[]` | Properties to retrieve |
+ */
+export const PluginGridGetArgs = z.object({
+  gridId: z.string(),
+  properties: z.array(PluginGridGetProperty),
+})
+export type PluginGridGetArgs = z.infer<typeof PluginGridGetArgs>
+
+/**
+ * Result of {@linkcode PluginDesignQueryGridsApi.get} — only the requested
+ * properties are present.
+ */
+export const PluginGridGetResult = z
+  .object({
+    angle: z.number(),
+    props: PluginGridLineProps,
+    storeyVisibility: PluginGridStoreyVisibility,
+    wings: z.array(PluginGridWingRecord),
+    bounds: BBoxComponents,
+  })
+  .partial()
+export type PluginGridGetResult = z.infer<typeof PluginGridGetResult>
+
+// ---------------------------------------------------------------------------
+// Abstract API
+// ---------------------------------------------------------------------------
+
+/**
+ * `design.query.grids.*` — structural-grid-specific reads.
+ *
+ * A **grid** (grid group) is a structural/documentation grid: one or more
+ * *wings* (families of parallel lines with a shared local frame), each holding
+ * tagged grid *lines* (straight lines, or a lone arc). Enumerate grids with
+ * `design.query.listGrids`; read an individual grid's structure here.
+ *
+ * Lines have no stable identity of their own — mutating APIs address them
+ * positionally as `{ wing, line }` index pairs into the `wings` arrays
+ * returned by {@linkcode get}. Structural edits (adding/removing lines,
+ * count changes) re-index lines; re-query after mutating.
+ *
+ * Accessed via `snaptrude.design.query.grids`.
+ */
+export abstract class PluginDesignQueryGridsApi {
+  constructor() {}
+
+  /**
+   * Get properties of a grid by its ID.
+   *
+   * Only the properties listed in `properties` are returned — unlisted
+   * properties will be `undefined` in the result. `wings` is the heavy
+   * read (it registers a world-space {@linkcode CurveHandle} per line);
+   * request it only when the geometry is needed.
+   *
+   * Units: `angle` is in **degrees** (positive = CCW about +Y); `spacing`,
+   * `span`, `bounds`, and curve coordinates are in **Snaptrude units**,
+   * world space.
+   *
+   * @param gridId - The unique grid group ID
+   * @param properties - Array of property names to retrieve. See
+   *   {@linkcode PluginGridGetProperty}.
+   * @returns A partial {@linkcode PluginGridGetResult} containing only the
+   *   requested properties
+   * @throws If the grid does not exist
+   *
+   * @examplePrompt What is the spacing of this grid?
+   * @examplePrompt Read the grid line tags on this structural grid
+   * @examplePrompt Get the geometry of every line in this grid
+   * @examplePrompt Which storeys is this grid hidden on?
+   *
+   * # Example
+   * ```ts
+   * const [grid] = await snaptrude.design.query.listGrids()
+   * const { wings } = await snaptrude.design.query.grids.get(grid, ["wings"])
+   * // wings[0].lines[0].curve is an opaque CurveHandle in world space;
+   * // read its coordinates via `snaptrude.core.geom.curve`.
+   * ```
+   */
+  public abstract get(
+    gridId: string,
+    properties: z.infer<typeof PluginGridGetProperty>[],
+  ): PluginApiReturn<PluginGridGetResult>
+}