# Vue 3 프로젝트 적용

Vue 3 탭은 `<script setup>`과 `<template>`을 사용하는 실제 단일 파일 컴포넌트(SFC)입니다. [Vue 공식 안내](https://vuejs.org/api/sfc-script-setup.html)를 기준으로 작성했습니다.

## 파일 배치

기능별 `examples/vue-기능.vue`, `examples/data.js`, `examples/example-helpers.js`, `src/`를 같은 상대 경로 구조로 프로젝트에 복사하세요. 애플리케이션 진입 파일에서 `src/zixo.css`와 필요하면 `examples/demo.css`를 import합니다. 기존 Vue 3 + Vite 프로젝트에서 다음처럼 컴포넌트를 사용합니다.

```vue
<script setup>
import BasicGrid from './examples/vue-basic.vue';
import './src/zixo.css';
import './examples/demo.css';
</script>

<template>
  <BasicGrid />
</template>
```

`.vue`는 Vite의 Vue 플러그인처럼 SFC를 컴파일하는 빌드 환경에서 사용합니다. 로컬 HTML 실행은 동일 SFC를 미리 컴파일한 `.component.js`를 사용합니다. 생성된 파일을 편집하지 말고 `.vue` 원본을 수정한 후 `npm run manual`을 실행하세요. 재생성에는 Vue 3의 `@vue/compiler-sfc`가 필요합니다. `npm install`과 `npm run prepare:vue`로 예제 실행 환경을 준비할 수 있습니다. 원본 컴포넌트에서는 `vue`를 import하며 vendor 런타임 경로에 의존하지 않습니다.

## DOM과 수명주기

`ref`로 자신의 그리드 호스트를 연결하고 `onMounted`에서 생성합니다. `onBeforeUnmount`에서 `destroy()`를 호출합니다. 검색 입력은 `v-model`, 도구 버튼은 `@click`, 결과 메시지는 `ref`를 사용합니다. 인스턴스는 일반 변수에 보관해 Vue의 깊은 Proxy 변환을 피합니다. 같은 컴포넌트를 여러 개 렌더해도 ID나 window 상태를 공유하지 않습니다.

## 데이터 변경과 이벤트

그리드 편집은 그리드 내부 모델에 반영됩니다. Vue 배열과 자동 양방향 연결되지는 않습니다. `setRows()`는 데이터를 교체하고 변경 이력을 초기화하므로 저장하지 않은 수정이 있는 경우 먼저 저장/원복 여부를 결정하세요. reactive 객체를 직접 전달하면 내부 structuredClone에 실패할 수 있으므로 Vue 상태에서 일반 데이터의 스냅샷을 만들어 전달합니다.

```js
import { shallowRef } from 'vue';
const gridRows = shallowRef([{ id: 1, name: '주문' }]);
// API 응답으로 새로운 일반 배열을 받은 뒤 명시적으로 반영합니다.
function replaceRows(serverRows) {
  gridRows.value = serverRows;
  grid.setRows(serverRows);
}
// 편집 결과를 부모에 전달하거나 저장할 때 사용합니다.
const changes = grid.getChangedRows();
const currentRows = grid.model.getRows();
```

`shallowRef`는 배열 내부를 Proxy로 바꾸지 않습니다. 일반 `ref`/`reactive`를 사용했다면 중첩 객체까지 일반 데이터로 변환하세요. 행 데이터의 날짜·함수 등 타입에 따라 변환 방법을 결정해야 하므로 JSON 직렬화를 모든 데이터에 일괄 적용하지 마세요. 옵션의 columns 및 plugins에는 함수와 인스턴스가 있으므로 JSON 복사하지 않습니다.

부모에서 API에 접근하려면 컴포넌트 ref의 `getGrid()`를 사용합니다. `getGrid()`는 마운트 전·해제 후에는 undefined입니다. 조회/저장 콜백은 signal을 실제 fetch에 전달하고 컴포넌트 해제 이후 UI를 갱신하지 않도록 처리하세요.

## Git에서 새로 받은 예제 실행

`npm install` 후 `npm start`로 실행하면 개발 서버가 설치된 Vue 런타임을 예제 URL로 직접 제공합니다. Git에서 제외된 examples/vendor 파일이 없어도 별도 복사 없이 Vue3 탭을 사용할 수 있습니다. 정적 파일 서버에 배포할 때는 `npm run prepare:vue`로 런타임을 복사하세요. 모듈을 불러오지 못하면 예제에 오류 안내가 표시됩니다.