Skip to content

AI-native design editor. Open-source Figma alternative.

15.1 KB
Raw Blame
import type { SceneGraph, SceneNode } from '@open-pencil/scene-graph'
import Matrix from '@open-pencil/scene-graph/matrix'
import type { Rect, Vector } from '@open-pencil/scene-graph/primitives'

import {
  ISSUE_EDGE_ARROW,
  ISSUE_EDGE_MERGE_GAP,
  ISSUE_MARKER_GAP,
  ISSUE_MARKER_HEIGHT,
  ISSUE_MARKER_MAX_COUNT,
  ISSUE_MARKER_MIN_TARGET,
  ISSUE_MARKER_OFFSET,
  ISSUE_MARKER_PADDING_X,
  ISSUE_MARKER_RING_WIDTH,
  ISSUE_MARKER_VIEWPORT_INSET
} from '#core/constants'
import {
  createSceneGeometry,
  type RotationPreview,
  type SceneGeometry,
  type ViewportTransform
} from '#core/geometry'

import type { DesignIssueMarker, DesignIssueSeverity, PlacedIssueMarker } from './types'

export interface IssueMarkerView extends ViewportTransform {
  width: number
  height: number
  /** Space taken by chrome along the top and left edges, such as rulers. */
  insetTop: number
  insetLeft: number
}

/** What places markers in the document, which pan and zoom leave alone. */
export interface IssueMarkerStageOptions {
  pageId: string
  /** Layers whose markers would cover an active edit, such as the text being typed. */
  suppressedIds?: ReadonlySet<string>
  preview?: RotationPreview | null
}

/** What places staged markers on the screen. */
export interface IssueMarkerPlacementOptions {
  view: IssueMarkerView
  measureText: (text: string) => number
  /** Screen rectangles of UI floating over the canvas, such as a toolbar, to keep pins clear of. */
  obstacles?: readonly Rect[]
}

export type IssueMarkerLayoutOptions = IssueMarkerStageOptions & IssueMarkerPlacementOptions

/** A marked layer as staged in world space, from which each frame places its marker. */
export interface StagedIssueMarker {
  marker: DesignIssueMarker
  /**
   * The world boxes a marker may attach to: the layer's, then each ancestor's up to the one under
   * the page, each clipped by the clipping layers above it and left out where clipped away.
   */
  targets: readonly Rect[]
}

const SEVERITY_RANK: Record<DesignIssueSeverity, number> = { error: 3, warning: 2, info: 1 }

export function issueSeverityRank(severity: DesignIssueSeverity): number {
  return SEVERITY_RANK[severity]
}

export function issueMarkerLabel(count: number): string {
  if (count <= 1) return '!'
  return count > ISSUE_MARKER_MAX_COUNT ? `${ISSUE_MARKER_MAX_COUNT}+` : String(count)
}

export function issueMarkerWidth(count: number, measureText: (text: string) => number): number {
  const textWidth = measureText(issueMarkerLabel(count))
  return Math.max(ISSUE_MARKER_HEIGHT, Math.ceil(textWidth + ISSUE_MARKER_PADDING_X * 2))
}

function intersect(a: Rect, b: Rect): Rect | null {
  const x = Math.max(a.x, b.x)
  const y = Math.max(a.y, b.y)
  const right = Math.min(a.x + a.width, b.x + b.width)
  const bottom = Math.min(a.y + a.height, b.y + b.height)
  if (right < x || bottom < y) return null
  return { x, y, width: right - x, height: bottom - y }
}

function overlaps(a: Rect, b: Rect, gap: number): boolean {
  return (
    a.x < b.x + b.width + gap &&
    b.x < a.x + a.width + gap &&
    a.y < b.y + b.height + gap &&
    b.y < a.y + a.height + gap
  )
}

/** The axis-aligned world box of a layer's rotated rectangle. */
function worldBounds(node: SceneNode, geometry: SceneGeometry): Rect {
  const points = Matrix.mapPoints(geometry.worldMatrix(node), [
    0,
    0,
    node.width,
    0,
    node.width,
    node.height,
    0,
    node.height
  ])
  let minX = Infinity
  let minY = Infinity
  let maxX = -Infinity
  let maxY = -Infinity
  for (let index = 0; index < points.length; index += 2) {
    minX = Math.min(minX, points[index])
    maxX = Math.max(maxX, points[index])
    minY = Math.min(minY, points[index + 1])
    maxY = Math.max(maxY, points[index + 1])
  }
  return { x: minX, y: minY, width: maxX - minX, height: maxY - minY }
}

/** A world box on the screen; the viewport pans and scales, so boxes stay axis-aligned. */
function toScreen(rect: Rect, view: ViewportTransform): Rect {
  return {
    x: rect.x * view.zoom + view.panX,
    y: rect.y * view.zoom + view.panY,
    width: rect.width * view.zoom,
    height: rect.height * view.zoom
  }
}

/**
 * The world boxes a layer's marker may attach to, or null when the layer should not be marked.
 *
 * Hidden and clipped-out layers stay listed in the panel but get no marker, so a marker never
 * points at empty canvas. Clipping is by axis-aligned boxes, which the viewport keeps, so what
 * shows is settled here once and projected per frame.
 */
function stageTargets(
  graph: SceneGraph,
  node: SceneNode,
  pageId: string,
  geometry: SceneGeometry
): Rect[] | null {
  const chain: SceneNode[] = []
  let current: SceneNode | undefined = node
  while (current) {
    if (!current.visible) return null
    chain.push(current)
    if (current.parentId === pageId) break
    current = current.parentId ? graph.getNode(current.parentId) : undefined
  }
  if (!current) return null

  // Clip each layer's bounds by the clipping ancestors above it, walking top-down. A clipping
  // layer that is entirely clipped away hides everything inside it.
  const visible = Array.from<Rect | null>({ length: chain.length })
  let clip: Rect | null = null
  for (let index = chain.length - 1; index >= 0; index--) {
    const layer = chain[index]
    const bounds = worldBounds(layer, geometry)
    const clipped: Rect | null = clip ? intersect(bounds, clip) : bounds
    visible[index] = clipped
    if (!layer.clipsContent) continue
    if (!clipped) return null
    clip = clipped
  }
  if (!visible[0]) return null
  return visible.filter((bounds): bounds is Rect => bounds !== null)
}

/**
 * Stages the markers' layers in world space: what each marker may attach to, with hidden,
 * clipped-away, and suppressed layers left out. Pan and zoom change none of it, so a canvas keeps
 * the stage until the document or the markers change.
 */
export function stageIssueMarkers(
  graph: SceneGraph,
  markers: readonly DesignIssueMarker[],
  options: IssueMarkerStageOptions
): StagedIssueMarker[] {
  const { pageId, suppressedIds } = options
  const geometry = createSceneGeometry(graph, options.preview)
  const staged: StagedIssueMarker[] = []
  for (const marker of markers) {
    if (marker.count <= 0 || suppressedIds?.has(marker.nodeId)) continue
    const node = graph.getNode(marker.nodeId)
    if (!node) continue
    const targets = stageTargets(graph, node, pageId, geometry)
    if (targets) staged.push({ marker, targets })
  }
  return staged
}

/**
 * The screen rectangle a staged marker attaches to. A layer too small to point at on screen
 * hands its marker to the nearest ancestor that is large enough, so zoomed-out designs gather
 * markers at frame corners instead of scattering them over detail that cannot be seen.
 */
function markerTarget(targets: readonly Rect[], view: ViewportTransform): Rect {
  const last = targets[targets.length - 1]
  for (const bounds of targets) {
    if (Math.max(bounds.width, bounds.height) * view.zoom >= ISSUE_MARKER_MIN_TARGET)
      return toScreen(bounds, view)
  }
  return toScreen(last, view)
}

interface Candidate {
  marker: DesignIssueMarker
  anchor: Vector
}

interface EdgeCandidate {
  marker: DesignIssueMarker
  /** Where the ray toward the layer leaves the viewport. */
  point: Vector
  direction: Vector
  distance: number
}

/**
 * Where the ray from the viewport center toward a layer leaves `area`, so an off-screen issue
 * is pinned in its own direction, on a side or in a corner.
 */
function edgePoint(
  area: Rect,
  target: Vector
): { point: Vector; direction: Vector; distance: number } {
  const center = { x: area.x + area.width / 2, y: area.y + area.height / 2 }
  const dx = target.x - center.x
  const dy = target.y - center.y
  const distance = Math.hypot(dx, dy) || 1
  const direction = { x: dx / distance, y: dy / distance }
  const tx = direction.x === 0 ? Infinity : area.width / 2 / Math.abs(direction.x)
  const ty = direction.y === 0 ? Infinity : area.height / 2 / Math.abs(direction.y)
  const t = Math.min(tx, ty)
  return {
    point: { x: center.x + direction.x * t, y: center.y + direction.y * t },
    direction,
    distance
  }
}

/** Slides a pin along the edge it sits on until it no longer covers floating UI. */
function avoidObstacles(rect: Rect, area: Rect, obstacles: readonly Rect[]): Rect {
  let placed = rect
  for (const obstacle of obstacles) {
    if (!overlaps(placed, obstacle, ISSUE_MARKER_GAP)) continue
    const onHorizontalEdge =
      placed.y <= area.y + 1 || placed.y + placed.height >= area.y + area.height - 1
    if (onHorizontalEdge) {
      const left = obstacle.x - ISSUE_MARKER_GAP - placed.width
      const right = obstacle.x + obstacle.width + ISSUE_MARKER_GAP
      const x =
        Math.abs(left - placed.x) <= Math.abs(right - placed.x) && left >= area.x
          ? left
          : Math.min(right, area.x + area.width - placed.width)
      placed = { ...placed, x }
    } else {
      const above = obstacle.y - ISSUE_MARKER_GAP - placed.height
      const below = obstacle.y + obstacle.height + ISSUE_MARKER_GAP
      const y =
        Math.abs(above - placed.y) <= Math.abs(below - placed.y) && above >= area.y
          ? above
          : Math.min(below, area.y + area.height - placed.height)
      placed = { ...placed, y }
    }
  }
  return placed
}

/**
 * Pins issues outside the viewport to its edge, in their direction. Pins near each other along
 * the edge merge, keeping the most severe; each lists its layers most severe first, then
 * nearest, so following a pin reaches the closest issue of the severity it shows.
 */
function layoutEdgePins(
  candidates: EdgeCandidate[],
  area: Rect,
  obstacles: readonly Rect[],
  measureText: (text: string) => number
): PlacedIssueMarker[] {
  candidates.sort(
    (a, b) =>
      SEVERITY_RANK[b.marker.severity] - SEVERITY_RANK[a.marker.severity] || a.distance - b.distance
  )
  const rectAt = (point: Vector, count: number): Rect => {
    const width = issueMarkerWidth(count, measureText)
    const x = Math.min(Math.max(point.x - width / 2, area.x), area.x + area.width - width)
    const y = Math.min(
      Math.max(point.y - ISSUE_MARKER_HEIGHT / 2, area.y),
      area.y + area.height - ISSUE_MARKER_HEIGHT
    )
    const rect = { x: Math.round(x), y: Math.round(y), width, height: ISSUE_MARKER_HEIGHT }
    return avoidObstacles(rect, area, obstacles)
  }
  type Pin = PlacedIssueMarker & { point: Vector; order: Map<string, [number, number]> }
  const pins: Pin[] = []
  for (const { marker, point, direction, distance } of candidates) {
    const rect = rectAt(point, marker.count)
    const pin = pins.find((existing) => overlaps(existing.rect, rect, ISSUE_EDGE_MERGE_GAP))
    if (pin) {
      pin.nodeIds.push(marker.nodeId)
      pin.order.set(marker.nodeId, [SEVERITY_RANK[marker.severity], distance])
      pin.count += marker.count
      pin.rect = rectAt(pin.point, pin.count)
      continue
    }
    pins.push({
      key: `edge:${marker.nodeId}`,
      nodeIds: [marker.nodeId],
      severity: marker.severity,
      count: marker.count,
      rect,
      anchor: point,
      direction,
      point,
      order: new Map([[marker.nodeId, [SEVERITY_RANK[marker.severity], distance]]])
    })
  }
  const rank = (order: Pin['order'], id: string) => order.get(id) ?? [0, 0]
  return pins.map(({ point: _point, order, ...pin }) => ({
    ...pin,
    nodeIds: pin.nodeIds.toSorted((a, b) => {
      const [severityA, distanceA] = rank(order, a)
      const [severityB, distanceB] = rank(order, b)
      return severityB - severityA || distanceA - distanceB
    })
  }))
}

/**
 * Places one marker at the outer top-right corner of each staged layer, then merges markers that
 * would overlap. Merging keeps the position of the most severe marker, so the canvas never shows
 * a warning on top of an error it hides.
 */
export function placeIssueMarkers(
  staged: readonly StagedIssueMarker[],
  options: IssueMarkerPlacementOptions
): PlacedIssueMarker[] {
  const { view, measureText } = options
  const viewport: Rect = {
    x: view.insetLeft,
    y: view.insetTop,
    width: Math.max(0, view.width - view.insetLeft),
    height: Math.max(0, view.height - view.insetTop)
  }

  const candidates: Candidate[] = []
  const edgeCandidates: EdgeCandidate[] = []
  // Edge pins keep room between themselves and the edge for the chevron they point with.
  const edgeInset = ISSUE_MARKER_VIEWPORT_INSET + ISSUE_EDGE_ARROW + ISSUE_MARKER_RING_WIDTH * 2
  const edgeArea: Rect = {
    x: viewport.x + edgeInset,
    y: viewport.y + edgeInset,
    width: Math.max(0, viewport.width - edgeInset * 2),
    height: Math.max(0, viewport.height - edgeInset * 2)
  }
  for (const { marker, targets } of staged) {
    const bounds = markerTarget(targets, view)
    if (intersect(bounds, viewport)) {
      candidates.push({ marker, anchor: { x: bounds.x + bounds.width, y: bounds.y } })
      continue
    }
    const center = { x: bounds.x + bounds.width / 2, y: bounds.y + bounds.height / 2 }
    edgeCandidates.push({ marker, ...edgePoint(edgeArea, center) })
  }

  candidates.sort(
    (a, b) =>
      SEVERITY_RANK[b.marker.severity] - SEVERITY_RANK[a.marker.severity] ||
      a.anchor.y - b.anchor.y ||
      b.anchor.x - a.anchor.x
  )

  const minX = viewport.x + ISSUE_MARKER_VIEWPORT_INSET
  const minY = viewport.y + ISSUE_MARKER_VIEWPORT_INSET
  const maxRight = view.width - ISSUE_MARKER_VIEWPORT_INSET
  const maxBottom = view.height - ISSUE_MARKER_VIEWPORT_INSET

  function rectAt(anchor: Vector, count: number): Rect {
    const width = issueMarkerWidth(count, measureText)
    const x = Math.min(Math.max(anchor.x + ISSUE_MARKER_OFFSET, minX), maxRight - width)
    const y = Math.min(
      Math.max(anchor.y - ISSUE_MARKER_OFFSET - ISSUE_MARKER_HEIGHT, minY),
      maxBottom - ISSUE_MARKER_HEIGHT
    )
    return { x: Math.round(x), y: Math.round(y), width, height: ISSUE_MARKER_HEIGHT }
  }

  const placed: PlacedIssueMarker[] = []
  for (const { marker, anchor } of candidates) {
    const rect = rectAt(anchor, marker.count)
    const target = placed.find((existing) => overlaps(existing.rect, rect, ISSUE_MARKER_GAP))
    if (target) {
      target.nodeIds.push(marker.nodeId)
      target.count += marker.count
      target.rect = rectAt(target.anchor, target.count)
      continue
    }
    placed.push({
      key: marker.nodeId,
      nodeIds: [marker.nodeId],
      severity: marker.severity,
      count: marker.count,
      rect,
      anchor
    })
  }
  const edgePins = layoutEdgePins(edgeCandidates, edgeArea, options.obstacles ?? [], measureText)
  return [...placed, ...edgePins]
}

/** Stages and places markers in one go, for a layout that is not kept between frames. */
export function layoutIssueMarkers(
  graph: SceneGraph,
  markers: readonly DesignIssueMarker[],
  options: IssueMarkerLayoutOptions
): PlacedIssueMarker[] {
  return placeIssueMarkers(stageIssueMarkers(graph, markers, options), options)
}

/** Topmost marker under a screen point; markers placed first are drawn on top. */
export function hitTestIssueMarkers(
  placed: readonly PlacedIssueMarker[],
  x: number,
  y: number
): PlacedIssueMarker | null {
  for (const marker of placed) {
    const { rect } = marker
    if (x >= rect.x && x <= rect.x + rect.width && y >= rect.y && y <= rect.y + rect.height) {
      return marker
    }
  }
  return null
}