@things-factory/figure-ui 10.1.3

package/client/modeller/figure-canvas.ts

@@ -0,0 +1,482 @@
+import { css, html, LitElement, unsafeCSS } from 'lit'
+import { customElement, property, query, state } from 'lit/decorators.js'
+
+import { i18next, localize } from '@operato/i18n'
+import { create, Model } from '@hatiolab/things-scene'
+
+import { gridStep } from './part-edits.js'
+import { DEFAULT_VIEW, WORKBENCH } from './figure-view.js'
+import type { ViewSettings } from './figure-view.js'
+import type { BoardModel, PartModel } from './figure-source.js'
+
+/**
+ * 판의 종이 색 — 거의 흰색.
+ *
+ * 2D 편집 도구(손잡이 · 안내선 · 선택 테)가 어두운 색으로 그려진다. 종이가 어두우면
+ * 그것들이 안 보여 편집을 할 수 없다. 순백이 아닌 것은 판의 가장자리가 작업면과
+ * 구별되게 하려는 것이다.
+ */
+const PAPER = '#f4f4f4'
+
+/**
+ * 달라진 값만 골라 낸다. 같은 것뿐이면 `null`.
+ *
+ * 값 비교는 JSON 으로 한다 — 경로(`path`)처럼 배열인 값이 있어서 얕은 비교로는 늘
+ * 다르다고 나온다.
+ */
+function changedKeys(
+  now: Record<string, unknown>,
+  wanted: Record<string, unknown>
+): Record<string, unknown> | null {
+  const diff: Record<string, unknown> = {}
+  let any = false
+
+  for (const [key, value] of Object.entries(wanted)) {
+    const before = now[key]
+    const same =
+      before === value || (before !== undefined && JSON.stringify(before) === JSON.stringify(value))
+    if (!same) {
+      diff[key] = value
+      any = true
+    }
+  }
+
+  return any ? diff : null
+}
+
+/** 씬이 돌려주는 것 중 우리가 쓰는 부분. */
+interface SceneHandle {
+  dispose?: () => void
+  resize?: () => void
+  /** 모델 전체가 보이게 화면에 맞춘다. 'ratio' 는 비율을 지키며 맞춘다. */
+  fit?: (type?: string) => void
+  /**
+   * **판**이다 — 루트가 아니다.
+   *
+   * `create()` 가 돌려주는 `root` 는 `model-layer` 이고, 그 위에 진짜 루트가 하나 더
+   * 있다. 부품은 판에 붙고, 선택 알림은 루트가 낸다. 둘을 섞으면 알림이 안 온다 —
+   * 실제로 그랬다.
+   */
+  root?: SceneBoard
+}
+
+interface SceneBoard {
+  invalidate?: () => void
+  /** 보기 설정을 넣는 자리. 씬이 스스로 반응한다. */
+  set?: (patch: Record<string, unknown>) => void
+  /** 3D 카메라를 모델 전체가 보이게 맞춘다. 10.1.4 부터 있다. */
+  fitCameraToModel?: (margin?: number) => void
+  components?: SceneComponent[]
+  selected?: SceneComponent[]
+  app?: unknown
+  addComponent?: (component: unknown) => void
+  on?: (event: string, handler: (...args: unknown[]) => void) => void
+  /** 판 위의 루트. 선택 알림이 여기서 난다. */
+  root?: {
+    selected?: SceneComponent[]
+    on?: (event: string, handler: (...args: unknown[]) => void) => void
+  }
+}
+
+interface SceneComponent {
+  state: Record<string, unknown>
+  set: (props: Record<string, unknown> | string, value?: unknown) => void
+  on?: (event: string, handler: (...args: unknown[]) => void) => void
+  remove?: () => void
+}
+
+/**
+ * 편집 캔버스 — 부품들을 보드 위에 세우고, 여기서 고치게 한다.
+ *
+ * ## 미리보기가 아니다
+ *
+ * 한동안 이름이 figure-preview 였다. 원본을 컴파일해 컴포넌트 하나로 세우던 시절에는
+ * 정말 보기만 하는 화면이었다. 부품을 컴포넌트로 바꾸면서 편집이 여기서 일어나게 되었다.
+ * 부품을 고르고, 2D 로 바꿔 편집하고, 기즈모로 끄는 일이 전부 이 안에서 일어난다.
+ * 이름만 남아 있었다.
+ *
+ * ## 부품이 컴포넌트다
+ *
+ * 한동안 원본 데이터를 컴파일해 **컴포넌트 하나**로 놓고, 그 안에서 부품을 찾아 다뤘다.
+ * 배포용 형태를 편집 화면에 그대로 쓴 것이다. 그래서 어느 부품이 선택됐나 · 무엇을 감쌀까 ·
+ * 무엇을 끌까를 전부 따로 뚫어야 했다.
+ *
+ * 이제 부품 하나가 컴포넌트 하나다. 선택 · 기즈모 · 윤곽선 · 다중 선택 · 되돌리기가
+ * 씬의 기본 동작으로 그냥 된다.
+ *
+ * ## 보드가 곧 기준 상자다
+ *
+ * 보드의 `width` · `height` · `depth` 가 `FigureSource.base` 다. 부품 좌표를 변환할 때
+ * 보드 중심만 빼면 된다 — `figure-source.ts` 가 그 일을 한다.
+ *
+ * ## 다시 세우지 않는다
+ *
+ * 부품이 바뀌면 씬을 통째로 다시 세우지 않고 **바뀐 컴포넌트만 고친다.** 다시 세우면
+ * 고른 것과 카메라가 날아가서, 숫자 하나 고칠 때마다 화면이 처음으로 돌아간다.
+ * 판 크기가 바뀔 때만 다시 세운다 — 판은 씬을 만들 때 정해진다.
+ */
+@customElement('figure-canvas')
+export class FigureCanvas extends localize(i18next)(LitElement) {
+  static styles = css`
+    /*
+      판 바깥을 우리가 칠한다.
+
+      무대에는 셋이 있다 — 판의 면(2D 는 종이, 3D 는 바닥판), 판 바깥, 좌표 바탕.
+      어느 것도 원본 데이터에 저장되지 않는다. 보려고 만든 것이므로 편집하기 좋게 잡는다.
+
+      2D 에는 바깥을 칠하는 사람이 없다. 씬의 2D 는 캔버스를 투명으로 지우고
+      끝이라(layer.ts 의 clearRect), 뒤에 있는 것이 그대로 비친다. 테마 토큰을
+      깔아 두었더니 어두운 데서 까맣게 나왔다.
+
+      3D 하늘과 같은 값을 쓴다. 갈리면 2D 로 갔을 때 바탕색이 바뀐다.
+    */
+    :host {
+      position: relative;
+      display: flex;
+      overflow: hidden;
+      background-color: ${unsafeCSS(WORKBENCH)};
+    }
+
+    /*
+      씬이 이 칸을 자기 것으로 삼으면서 인라인 스타일로 position: relative 를 박는다.
+
+      그러면 우리가 CSS 로 준 position: absolute 가 밀리고, 같이 준 inset: 0 도 함께 뜻을
+      잃는다. relative 인 블록은 상위 배치에서 크기를 받는데, 자식(캔버스)이 전부 절대 배치라
+      내용 폭이 0 이다. 그래서 폭 0 짜리 칸이 되고 캔버스도 폭 0 이 된다.
+
+      화면은 그냥 회색으로 남는다. 게다가 마우스 좌표를 NDC 로 바꿀 때 폭으로 나누므로
+      값이 무한대가 되어 기즈모를 집을 수 없다 — "기즈모가 안 잡힌다"의 실제 원인이
+      이것이었다.
+
+      그래서 width 와 height 를 직접 준다. 인라인으로 position 이 무엇으로 바뀌든 칸은
+      부모를 채운다.
+    */
+    div[stage] {
+      position: absolute;
+      inset: 0;
+      width: 100%;
+      height: 100%;
+    }
+
+    /* 세울 수 없는 상태를 빈 화면으로 두지 않는다 — 왜 안 보이는지 말한다 */
+    div[cannot] {
+      position: absolute;
+      inset: 0;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      padding: var(--spacing-large, 12px);
+      text-align: center;
+      font: var(--label-font, inherit);
+      line-height: 1.6;
+      color: var(--md-sys-color-on-surface-variant, var(--md-sys-color-on-surface));
+      background-color: ${unsafeCSS(WORKBENCH)};
+    }
+  `
+
+  /**
+   * 편집 중인 내용. **씬 모델 그대로 받는다.**
+   *
+   * 한동안 `FigureSource` 로 받아 여기서 변환했다. 그런데 모델러 페이지가 갖고 있는 것이
+   * 이미 씬 모델이므로, 그러면 값을 하나 고칠 때마다 왕복 변환이 한 번씩 일어난다.
+   * 무손실이긴 하지만 하는 일이 없다 — 보드가 곧 보드이고 부품이 곧 컴포넌트다.
+   */
+  @property({ type: Object }) board?: BoardModel
+  /** 보기 설정. 자산이 아니라 작업대다 — 저장되지 않는다(`figure-view.ts`). */
+  @property({ type: Object }) view: ViewSettings = DEFAULT_VIEW
+  @property({ type: Array }) parts: PartModel[] = []
+  /** 지금 고른 부품 이름. 목록에서 고른 것을 캔버스에 알린다. */
+  @property({ type: String }) picked?: string
+
+  /**
+   * 보기 전용 — 씬에서 일어난 일을 밖에 알리지 않는다.
+   *
+   * AI 후보를 나란히 세울 때 쓴다. 후보는 아직 편집 대상이 아닌데, 씬은 컴포넌트를
+   * 만들면서 상태를 정리하고 그때 변경 이벤트를 낸다. 그 이벤트가 그대로 올라가면
+   * **후보의 값이 편집 중인 데이터를 덮어쓴다** — 실제로 그랬다. 받지 않기로 한 부품
+   * 위치가 오류보고없이 반영되어 있었고, 후보를 버려도 되돌아오지 않았다.
+   */
+  @property({ type: Boolean }) viewOnly = false
+
+  @query('div[stage]') private stage!: HTMLDivElement
+
+  /** 세울 수 없는 사유. 없으면 세운 것이다. */
+  @state() private cannot = ''
+
+  private scene?: SceneHandle
+  /** 지금 씬이 서 있는 판. 이것이 달라지면 다시 세운다. */
+  private standing?: string
+  /** 칸 크기를 따라가게 지켜본다. 안 지켜보면 0x0 으로 고정된다. */
+  private watcher?: ResizeObserver
+
+  render() {
+    return html`
+      <div stage></div>
+      ${this.cannot ? html`<div cannot>${this.cannot}</div>` : ''}
+    `
+  }
+
+  willUpdate(changed: Map<string, unknown>) {
+    if (!this.hasUpdated) return
+
+    if (changed.has('board') || changed.has('parts')) this.standUp()
+    if (changed.has('view')) this.applyView()
+    if (changed.has('picked')) this.showPicked()
+  }
+
+  firstUpdated() {
+    this.standUp()
+
+    // 씬은 세울 때의 칸 크기를 읽는다. 저작면이 아직 배치되기 전이면 0x0 으로 굳어
+    // **캔버스는 붙었는데 아무것도 안 보이는** 상태가 된다 — 실제로 그렇게 났다.
+    this.watcher = new ResizeObserver(() => this.scene?.resize?.())
+    this.watcher.observe(this)
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback()
+    this.watcher?.disconnect()
+    this.watcher = undefined
+    this.teardown()
+  }
+
+  /**
+   * 받은 것을 씬에 반영한다.
+   *
+   * **판이 그대로면 다시 세우지 않는다.** 다시 세우면 고른 것과 카메라가 날아가서,
+   * 숫자 하나 고칠 때마다 화면이 처음으로 돌아간다.
+   */
+  private standUp() {
+    const board = this.board
+    if (!board) {
+      this.cannot = i18next.t('text.canvas-appears-once-a-part-exists')
+      return
+    }
+
+    const signature = `${board.width}x${board.height}x${board.depth}`
+    if (this.scene && this.standing === signature) {
+      this.syncParts()
+      return
+    }
+
+    this.teardown()
+
+    try {
+      this.scene = create({
+        target: this.stage,
+        model: {
+          type: 'model-layer',
+          width: board.width,
+          height: board.height,
+          depth: board.depth,
+          threed: true,
+          environment: 'studio',
+          /*
+            표본을 화면보다 더 쓴다. MSAA 만으로는 실루엣의 계단이 남는다 — 픽셀
+            비율만 올려 보니 눈에 띄게 매끄러워졌다. 저작면은 작은 칸에 자산 하나라
+            그릴 것이 적으니 표본을 더 써도 된다.
+          */
+          pixelRatio: Math.min(3, (window.devicePixelRatio || 1) * 2),
+          /*
+            좌표 바탕을 씬에게 맡긴다. 우리가 만들어 얹었더니 2D 로 갔다 오면
+            사라졌다 — 그때 씬이 통째로 다시 서면서 새 THREE.Scene 을 만들기 때문이다.
+            보드는 이 값을 안 주므로 안 보인다.
+          */
+          ...this.sceneView(),
+          gridStep: gridStep(board),
+          sky: 'color',
+          /*
+            판의 면 — 2D 는 밝은 종이, 3D 는 없음.
+
+            종이는 밝아야 한다: 2D 편집 손잡이와 안내선이 어두운 색이다. 바닥판은
+            없어야 한다: 좌표 모눈과 겹쳐 싸우고 원점 아래쪽을 가린다.
+          */
+          fillStyle: PAPER,
+          components: this.parts.map(part => ({ ...part }))
+        },
+        // **편집 모드**로 만든다. 보드의 3D 모델러가 그 모드에서 카메라 시점 버튼 ·
+        // 기즈모 모드 · 도움말 · 단축키를 띄운다.
+        mode: 1
+      }) as SceneHandle
+
+      this.standing = signature
+      this.watchScene()
+      this.scene.resize?.()
+      /*
+        열자마자 모델 전체가 보이게 맞춘다.
+
+        카메라는 2D 뷰포트에서 만들어진다. 그런데 그 뷰포트의 처음 배율은 컨테이너
+        크기에서 오지 모델 크기에서 오지 않는다. 그래서 가로로 긴 모델(컨베이어가
+        그렇다)을 열면 화면 밖으로 나가 벨트 한 조각만 보였다.
+
+        **다시 세울 때만 맞춘다.** 창 크기가 바뀔 때마다 맞추면 사용자가 돌려 둔 시점과
+        확대가 매번 되돌아간다.
+      */
+      this.scene.fit?.('ratio')
+      /*
+        3D 카메라는 2D 쪽 fit 으로 안 움직인다. 처음 3D 로 설 때 모델 크기를 보지 않기
+        때문이다. 씬이 내주는 자리로 따로 맞춘다.
+
+        `?.` 로 부르는 것은 배포된 판에 아직 없을 수 있어서다. 없으면 2D 만 맞고 3D 는
+        기본 시점으로 선다 — 여기서 카메라 계산을 흉내 내지 않는다.
+      */
+      this.scene.root?.fitCameraToModel?.()
+      this.cannot = ''
+    } catch (e) {
+      // 원인을 지어내지 않는다 — 던진 말을 그대로 보여 준다.
+      this.cannot = (e as Error).message
+    }
+  }
+
+  /**
+   * 지금 판 위에 있는 부품 컴포넌트를 이름으로 찾는다.
+   *
+   * **참조를 들고 있지 않는다.** 전에는 세울 때 한 번 색인해 두고 계속 그 Map 을 썼다.
+   * 그런데 씬은 우리 모르게 판을 다시 세울 때가 있다 — 2D 와 3D 를 오갈 때가 그렇다.
+   * 그러면 Map 안의 것들은 부모가 없는 죽은 객체가 되고, 그 뒤로는
+   *
+   *   - 목록에서 골라도 선택이 안 된다. 루트의 `selected` 게터가 부모 없는 것을
+   *     걸러 내므로 빈 배열이 되고, 테두리도 기즈모도 붙지 않는다
+   *   - 속성을 고쳐도 3D 가 안 따라온다. 죽은 객체에 값을 넣기 때문이다
+   *
+   * 둘 다 오류보고없이 일어난다. 실제로 화면에서 「기즈모가 안 잡힌다」로 나타났다.
+   *
+   * 부품은 많아야 20개다. 매번 순회하는 값이 참조를 갖고 있다가 틀리는 값보다 훨씬 싸다.
+   */
+  private partsOnBoard(): Map<string, SceneComponent> {
+    const found = new Map<string, SceneComponent>()
+    for (const component of this.scene?.root?.components ?? []) {
+      const name = component.state?.name
+      if (typeof name === 'string') found.set(name, component)
+    }
+    return found
+  }
+
+  /**
+   * 보기 설정을 씬이 아는 이름으로 낸다.
+   *
+   * 옮겨 적는 표를 두지 않는다 — `ViewSettings` 의 이름이 곧 `model-layer` 의 상태
+   * 이름이다. 표를 두면 씬이 새 설정을 받아도 이쪽이 모른다.
+   */
+  private sceneView(): Record<string, unknown> {
+    const { grid, gridLabels, floor, environment, skyColor, ...light } = this.view ?? DEFAULT_VIEW
+
+    return { grid, gridLabels, floor, environment, skyColor, ...light }
+  }
+
+  /**
+   * 설정이 바뀌면 **씬에 그대로 넣는다.** 다시 세우지 않는다.
+   *
+   * 씬이 이 값들에 스스로 반응한다(`three-capability` 의 `onchange`) — 조명 · 반사 ·
+   * 바닥 · 좌표 바탕이 그 자리에서 바뀐다. 다시 세우면 고른 것과 카메라가 날아가서,
+   * 밝기 하나 끄는 동안 화면이 계속 처음으로 돌아간다.
+   */
+  private applyView(): void {
+    const board = this.scene?.root
+    if (!board) return
+
+    board.set?.(this.sceneView())
+    board.invalidate?.()
+  }
+
+  /**
+   * 부품 목록을 씬에 맞춘다. **다시 세우지 않고 바뀐 것만 고친다.**
+   *
+   * 다시 세우면 고른 것과 카메라가 날아가서, 숫자 하나 고칠 때마다 화면이 처음으로
+   * 돌아간다.
+   */
+  private syncParts() {
+    const root = this.scene?.root
+    if (!root) return
+
+    const wanted = new Map(this.parts.map(part => [part.name, part]))
+    const standing = this.partsOnBoard()
+
+    // 없어진 것을 제거한다
+    for (const [name, component] of standing) {
+      if (!wanted.has(name)) component.remove?.()
+    }
+
+    for (const part of this.parts) {
+      const found = standing.get(part.name)
+      if (found) {
+        /*
+          **달라진 값만 넣는다.**
+
+          같은 값을 다시 넣어도 씬은 변경 이벤트를 낸다. 그 이벤트가 다시 편집 데이터를
+          만들고, 그것이 다시 여기로 돌아오면 끝없이 반복된다. 기즈모를 끄는 중이라면 그
+          되먹임이 끌기와 싸운다.
+        */
+        const diff = changedKeys(found.state, part as unknown as Record<string, unknown>)
+        if (diff) found.set(diff)
+        continue
+      }
+      // 새 부품. 씬의 공장으로 만들어 판에 붙인다.
+      const made = Model.compile({ ...part }, root.app as never) as SceneComponent | null
+      if (made) root.addComponent?.(made)
+    }
+
+    root.invalidate?.()
+  }
+
+  /**
+   * 씬에서 일어난 일을 밖에 알린다.
+   *
+   * **자리가 아니라 이름으로 알린다.** 목록의 몇 번째인지로 알리면, 알림이 오는 사이에
+   * 목록이 바뀌면 엉뚱한 부품을 가리킨다.
+   */
+  private watchScene() {
+    const board = this.scene?.root
+    const root = board?.root
+    if (!board || !root?.on || this.viewOnly) return
+
+    root.on('selected', (after: unknown) => {
+      const chosen = (after as SceneComponent[] | undefined)?.[0]
+      const name = chosen?.state?.name
+      if (typeof name === 'string') this.tell('pick-part', { name })
+    })
+
+    /*
+      기즈모로 끌거나 2D 에서 옮기면 컴포넌트 상태가 바뀐다. 그것을 그대로 올려 보낸다 —
+      씬이 쓰는 용어 그대로다. 저장 형식으로 옮기는 일은 변환 함수가 한다.
+
+      **바뀜은 판으로 올라오고, 바뀐 컴포넌트는 끝 인자의 `origin` 에 있다.** 자식이
+      `trigger('change', after, before)` 를 하면 씬이 `{ origin, name, deliverer }` 를
+      뒤에 붙여 부모에게 넘긴다. 첫 인자를 컴포넌트로 읽으면 아무 일도 안 일어난다 —
+      실제로 그랬다.
+    */
+    board.on?.('change', (...args: unknown[]) => {
+      const hint = args[args.length - 1] as { origin?: SceneComponent } | undefined
+      const changed = hint?.origin
+      const name = changed?.state?.name
+      if (typeof name !== 'string') return
+
+      const was = this.parts.find(part => part.name === name)
+      if (!was) return
+
+      // 씬 모델 그대로 올려 보낸다. 모델러 페이지가 갖고 있는 것도 씬 모델이라 변환할 것이 없다.
+      this.tell('part-changed', { name, part: { ...was, ...changed!.state } as PartModel })
+    })
+  }
+
+  /** 목록에서 고른 것을 캔버스의 선택에 맞춘다. */
+  private showPicked() {
+    const board = this.scene?.root
+    const root = board?.root
+    if (!board || !root) return
+
+    const component = this.picked ? this.partsOnBoard().get(this.picked) : undefined
+    root.selected = component ? [component] : []
+    board.invalidate?.()
+  }
+
+  private tell(what: string, detail: object) {
+    this.dispatchEvent(new CustomEvent(what, { detail, bubbles: true, composed: true }))
+  }
+
+  private teardown() {
+    this.scene?.dispose?.()
+    this.scene = undefined
+    this.standing = undefined
+  }
+}