@mlightcad/cad-simple-viewer 1.7.5 → 1.7.6

package/src/find/AcApFindNavigator.ts

@@ -0,0 +1,190 @@
+import {
+  acdbHostApplicationServices,
+  AcGeBox2d,
+  AcGePoint2d
+} from '@mlightcad/data-model'
+
+import type { AcApDocManager } from '../app/AcApDocManager'
+import { acapFindHitBox, type AcApFindLayoutHit } from './findDrawing'
+
+/** Options for {@link acapNavigateToFindHit}. */
+export interface AcApFindNavigateOptions {
+  /**
+   * Activate the hit's layout when it is not the active one. Default `true`.
+   * When `false` a cross-layout hit is not navigated and `layout-mismatch`
+   * is returned.
+   */
+  activateLayout?: boolean
+  /** Margin passed to `zoomTo`. Default `1.1`. */
+  margin?: number
+  /**
+   * Maximum time (ms) to wait for the freshly activated layout to finish
+   * converting before zooming and selecting. Default 15000.
+   */
+  idleTimeoutMs?: number
+  /**
+   * Canvas area (CSS pixels from each edge) covered by UI such as a docked
+   * palette. The hit is framed and centred in the remaining visible part of
+   * the canvas so it never ends up hidden behind the palette.
+   */
+  insets?: AcApFindViewInsets
+}
+
+/** Pixels of the canvas covered on each side; see {@link AcApFindNavigateOptions.insets}. */
+export interface AcApFindViewInsets {
+  left?: number
+  right?: number
+  top?: number
+  bottom?: number
+}
+
+/** View methods used to keep the hit inside the uncovered canvas area. */
+interface InsetView {
+  width?: number
+  height?: number
+  center?: { x: number; y: number }
+  worldToScreen?(p: { x: number; y: number }): { x: number; y: number }
+  screenToWorld?(p: { x: number; y: number }): { x: number; y: number }
+}
+
+/**
+ * Zooms to `box` so that it fits, centred, in the part of the canvas that
+ * `insets` leaves visible. Falls back to a plain `zoomTo` when the view
+ * cannot convert coordinates or the visible part is too small to matter.
+ */
+function zoomToVisible(
+  view: InsetView & { zoomTo(box: AcGeBox2d, margin?: number): void },
+  box: { min: { x: number; y: number }; max: { x: number; y: number } },
+  margin: number,
+  insets: AcApFindViewInsets | undefined
+) {
+  const width = Number(view.width) || 0
+  const height = Number(view.height) || 0
+  const left = Math.max(0, insets?.left ?? 0)
+  const right = Math.max(0, insets?.right ?? 0)
+  const top = Math.max(0, insets?.top ?? 0)
+  const bottom = Math.max(0, insets?.bottom ?? 0)
+  const visibleW = width - left - right
+  const visibleH = height - top - bottom
+  const usable =
+    width > 0 &&
+    height > 0 &&
+    left + right + top + bottom > 0 &&
+    visibleW >= width * 0.2 &&
+    visibleH >= height * 0.2 &&
+    !!view.worldToScreen &&
+    !!view.screenToWorld
+  if (!usable) {
+    view.zoomTo(
+      new AcGeBox2d(
+        new AcGePoint2d(box.min.x, box.min.y),
+        new AcGePoint2d(box.max.x, box.max.y)
+      ),
+      margin
+    )
+    return
+  }
+  // Grow the box so that, fitted to the full canvas, its original part
+  // fits the visible part.
+  const cx = (box.min.x + box.max.x) / 2
+  const cy = (box.min.y + box.max.y) / 2
+  const halfW = ((box.max.x - box.min.x) / 2) * (width / visibleW)
+  const halfH = ((box.max.y - box.min.y) / 2) * (height / visibleH)
+  view.zoomTo(
+    new AcGeBox2d(
+      new AcGePoint2d(cx - halfW, cy - halfH),
+      new AcGePoint2d(cx + halfW, cy + halfH)
+    ),
+    margin
+  )
+  // Then pan so the hit sits in the middle of the visible part.
+  const hitOnScreen = view.worldToScreen!({ x: cx, y: cy })
+  const targetX = left + visibleW / 2
+  const targetY = top + visibleH / 2
+  const newCenter = view.screenToWorld!({
+    x: width / 2 + (hitOnScreen.x - targetX),
+    y: height / 2 + (hitOnScreen.y - targetY)
+  })
+  if (isFinite(newCenter.x) && isFinite(newCenter.y)) {
+    view.center = new AcGePoint2d(newCenter.x, newCenter.y)
+  }
+}
+
+/**
+ * Outcome of {@link acapNavigateToFindHit}.
+ *
+ * - `navigated`: layout (if needed) activated, view zoomed, entity selected
+ * - `layout-mismatch`: hit is in another layout and `activateLayout` is false
+ * - `layout-missing`: the hit's layout no longer exists in the drawing
+ * - `layout-switch-failed`: the layout manager refused / did not switch
+ * - `no-document`: no open drawing or view
+ * - `stale`: a newer navigation started while waiting; nothing was done
+ */
+export type AcApFindNavigateResult =
+  | 'navigated'
+  | 'layout-mismatch'
+  | 'layout-missing'
+  | 'layout-switch-failed'
+  | 'no-document'
+  | 'stale'
+
+const navigationTokens = new WeakMap<object, number>()
+
+/**
+ * Navigates to a FIND hit: activates its layout when needed, zooms to the text
+ * and selects the owning entity.
+ *
+ * Same-layout hits are handled synchronously (before the first `await`), so
+ * callers may ignore the returned promise in that case. For a hit in another
+ * layout the layout is activated through the document's layout manager; the
+ * first-visit auto zoom of that layout is suppressed (it would otherwise
+ * override this zoom), then the function waits for the layout's entities to
+ * be converted before selecting, because selection highlighting needs the
+ * entity to be present in the scene.
+ *
+ * @param editor - Document manager that owns the active view and drawing.
+ * @param hit - Hit returned by `acapFindText`.
+ */
+export async function acapNavigateToFindHit(
+  editor: AcApDocManager,
+  hit: AcApFindLayoutHit,
+  options: AcApFindNavigateOptions = {}
+): Promise<AcApFindNavigateResult> {
+  const view = editor.curView
+  const db = editor.curDocument?.database
+  if (!view || !db) return 'no-document'
+
+  const token = (navigationTokens.get(view) ?? 0) + 1
+  navigationTokens.set(view, token)
+
+  if (view.activeLayoutBtrId !== hit.layoutId) {
+    if (options.activateLayout === false) return 'layout-mismatch'
+    if (!db.tables.blockTable.getIdAt(hit.layoutId)) return 'layout-missing'
+
+    if (!view.isLayoutInitialized(hit.layoutId)) {
+      // We frame the layout ourselves; keep its first-visit auto zoom from
+      // running afterwards and overriding the zoom to the hit.
+      view.markLayoutAsInitialized(hit.layoutId)
+    }
+    acdbHostApplicationServices().layoutManager.setCurrentLayoutBtrId(
+      hit.layoutId,
+      db
+    )
+    if (view.activeLayoutBtrId !== hit.layoutId) return 'layout-switch-failed'
+
+    await view.waitUntilIdle(options.idleTimeoutMs ?? 15_000)
+    if (navigationTokens.get(view) !== token) return 'stale'
+    if (view.activeLayoutBtrId !== hit.layoutId) return 'stale'
+  }
+
+  const box = acapFindHitBox(db, hit.layoutId, hit)
+  zoomToVisible(
+    view as unknown as Parameters<typeof zoomToVisible>[0],
+    box,
+    options.margin ?? 1.1,
+    options.insets
+  )
+  view.selectionSet.clear()
+  view.selectionSet.add(hit.entityId)
+  return 'navigated'
+}

package/src/find/findDrawing.ts

@@ -0,0 +1,211 @@
+/**
+ * Whole-drawing text search (FIND across layouts).
+ *
+ * Builds on {@link acapFindTextInLayout}: every layout of the drawing (model
+ * space and each paper space, in tab order) is searched with the same rules,
+ * and every hit is tagged with the layout it lives in so a UI can show it and
+ * navigate there.
+ *
+ * Pure TypeScript with no runtime imports (structural database shape), shared
+ * by cad-simple-ui-plugin and the Vue cad-viewer.
+ */
+import {
+  ACAP_FIND_MAX_RESULTS,
+  type AcApFindDatabaseLike,
+  type AcApFindHit,
+  type AcApFindOptions,
+  acapFindTextInLayout
+} from './findText'
+
+/**
+ * Where to search.
+ *
+ * - `drawing` (default): every layout of the drawing
+ * - `layout`: only the layout that is currently active in the view
+ */
+export type AcApFindScope = 'drawing' | 'layout'
+
+/** One layout of the drawing (model space or paper space). */
+export interface AcApFindLayoutInfo {
+  /** Layout name as shown on the layout tab (e.g. `Model`, `Layout1`). */
+  name: string
+  /** Block table record id of the layout. */
+  btrId: string
+  /** Tab order; layouts are searched and listed in this order. */
+  tabOrder: number
+}
+
+/** A hit that also identifies the layout that contains it. */
+export interface AcApFindLayoutHit extends AcApFindHit {
+  /** Block table record id of the layout containing the hit. */
+  layoutId: string
+  /** Name of the layout containing the hit. */
+  layoutName: string
+}
+
+/** Result of one drawing-level search. */
+export interface AcApFindDrawingResult {
+  hits: AcApFindLayoutHit[]
+  /** True when more than `maxResults` entities matched. */
+  truncated: boolean
+}
+
+/** Options for {@link acapFindText}. */
+export interface AcApFindDrawingOptions extends AcApFindOptions {
+  /** Search scope; defaults to `drawing`. */
+  scope?: AcApFindScope
+  /**
+   * Block table record id of the layout currently shown. Required for the
+   * `layout` scope; also used as the only layout when the drawing exposes no
+   * layout objects.
+   */
+  currentLayoutId: string
+}
+
+interface LayoutLike {
+  layoutName?: string
+  tabOrder?: number
+  blockTableRecordId?: string
+}
+
+/** Database shape used to enumerate layouts. */
+export interface AcApFindLayoutsDatabaseLike {
+  objects?: {
+    layout?: { newIterator?(): Iterable<LayoutLike> }
+  }
+}
+
+/**
+ * Lists the layouts of a drawing sorted by tab order (model space first in
+ * practice). Returns an empty list when the drawing has no layout objects.
+ */
+export function acapListFindLayouts(
+  db: AcApFindLayoutsDatabaseLike
+): AcApFindLayoutInfo[] {
+  const table = db.objects?.layout
+  if (!table?.newIterator) return []
+  const layouts: AcApFindLayoutInfo[] = []
+  for (const layout of table.newIterator()) {
+    if (!layout.blockTableRecordId) continue
+    layouts.push({
+      name: layout.layoutName ?? '',
+      btrId: layout.blockTableRecordId,
+      tabOrder: Number(layout.tabOrder) || 0
+    })
+  }
+  return layouts.sort(
+    (a, b) => a.tabOrder - b.tabOrder || a.name.localeCompare(b.name)
+  )
+}
+
+/**
+ * Finds text in the whole drawing or in the current layout only.
+ *
+ * Layouts are visited in tab order and the result cap is shared, so
+ * `truncated` is true as soon as any match beyond `maxResults` exists in any
+ * searched layout. Search runs on the database, not on the rendered scene, so
+ * layouts that were never opened in the view are searched too.
+ */
+export function acapFindText(
+  db: AcApFindDatabaseLike & AcApFindLayoutsDatabaseLike,
+  query: string,
+  options: AcApFindDrawingOptions
+): AcApFindDrawingResult {
+  const max = options.maxResults ?? ACAP_FIND_MAX_RESULTS
+  const known = acapListFindLayouts(db)
+  const nameOf = (btrId: string) =>
+    known.find(layout => layout.btrId === btrId)?.name ?? ''
+
+  let targets: Array<{ btrId: string; name: string }>
+  if (options.scope === 'layout' || known.length === 0) {
+    targets = [
+      { btrId: options.currentLayoutId, name: nameOf(options.currentLayoutId) }
+    ]
+  } else {
+    targets = known.map(layout => ({ btrId: layout.btrId, name: layout.name }))
+  }
+
+  const result: AcApFindDrawingResult = { hits: [], truncated: false }
+  for (const target of targets) {
+    const found = acapFindTextInLayout(db, target.btrId, query, {
+      matchCase: options.matchCase,
+      maxResults: max - result.hits.length
+    })
+    for (const hit of found.hits) {
+      result.hits.push({
+        ...hit,
+        layoutId: target.btrId,
+        layoutName: target.name
+      })
+    }
+    if (found.truncated) {
+      result.truncated = true
+      break
+    }
+  }
+  return result
+}
+
+/** Axis-aligned 2D box in WCS (plain numbers; no geometry library needed). */
+export interface AcApFindBox {
+  min: { x: number; y: number }
+  max: { x: number; y: number }
+}
+
+type XY = { x: number; y: number }
+interface WithExtents {
+  geometricExtents?: { min: XY; max: XY }
+}
+
+/**
+ * View box for a hit: the text extents (`hit.extents` for nested text), widened so a short label does not
+ * zoom in absurdly far (at least ~10 text heights wide). Falls back to the
+ * hit position when the entity has no usable extents.
+ *
+ * @param layoutBtrId - Layout that contains the hit (`hit.layoutId`).
+ */
+export function acapFindHitBox(
+  db: AcApFindDatabaseLike,
+  layoutBtrId: string,
+  hit: AcApFindHit
+): AcApFindBox {
+  const btr = db.tables.blockTable.getIdAt(layoutBtrId)
+  const owner = btr?.getIdAt?.(hit.entityId) as
+    | (WithExtents & {
+        attributeIterator?: () => Iterable<WithExtents & { objectId: string }>
+      })
+    | undefined
+  let target: WithExtents | undefined = owner
+  if (hit.kind === 'attribute' && owner?.attributeIterator) {
+    for (const attribute of owner.attributeIterator()) {
+      if (attribute.objectId === hit.textEntityId) {
+        target = attribute
+        break
+      }
+    }
+  }
+  let min: XY
+  let max: XY
+  try {
+    // Text nested in a block / dimension / table: the search already
+    // resolved its WCS extents (the owner's extents are the whole block).
+    const extents = hit.extents ?? target?.geometricExtents
+    if (!extents || !isFinite(extents.min.x) || !isFinite(extents.max.x)) {
+      throw new Error('no extents')
+    }
+    min = extents.min
+    max = extents.max
+  } catch {
+    min = max = hit.position
+  }
+  const cx = (min.x + max.x) / 2
+  const cy = (min.y + max.y) / 2
+  const w = max.x - min.x
+  const h = max.y - min.y
+  const width = Math.max(w * 3, h * 10, 1e-3)
+  const height = Math.max(h * 3, width / 4, 1e-3)
+  return {
+    min: { x: cx - width / 2, y: cy - height / 2 },
+    max: { x: cx + width / 2, y: cy + height / 2 }
+  }
+}