# vfunc.js

> vfunc.js는 빌드가 필요 없는 순수 Vanilla JavaScript UI 라이브러리입니다(Apache-2.0). Virtual DOM 없이 innerHTML로 렌더링하고, 이벤트는 위임으로, 요소는 `data-ref`로 찾습니다. 기본 개념: HTML은 그대로 쓰고 제어가 필요한 곳만 vfunc로 만든다. 전역은 `vf` 하나입니다.

vfunc.js 1.0용입니다. 전체 레퍼런스는 llms-full.txt(이 파일의 영어판 + 사이트 가이드·API 레퍼런스 + 타입 선언)이고, 이 파일에는 올바른 코드를 쓰는 데 필요한 것만 담았습니다. 영어판 llms.txt와 같은 내용·같은 코드 예시입니다.

## 불러오기

- 스크립트 태그: `<script src="https://cdn.jsdelivr.net/npm/vfunc@1.2.0/dist/vfunc.min.js" integrity="sha384-yTR0o8US3nk+D1XIBAsv1O/lMFA5tV3V021xPo8yxyqnBNSxi1rqINVvBOykAEkK" crossorigin="anonymous"></script>` → 전역 `vf`. 운영에서는 정확한 버전과 SRI를 붙입니다. integrity 값은 버전·파일마다 다릅니다(이 값은 1.2.0의 vfunc.min.js). `dist/vfunc.js`는 경고가 나오는 개발용입니다.
- ES 모듈: `import vf from 'vfunc'` 또는 `import { vfunc, html, router } from 'vfunc'`. 복사한 파일도 같습니다(`import vf from './lib/vfunc.esm.min.js'`). ES 모듈은 `window.vf`를 건드리지 않습니다.
- IE11·Edge IE 모드: `dist/vfunc.legacy.min.js`(API 동일, Promise 폴리필만 포함). 앱 코드도 ES5여야 합니다. 화살표 함수·const/let·템플릿 리터럴·클래스를 쓰지 말고, vf.html 템플릿 리터럴 대신 `vf.tpl('<b>{name}</b>', data)`을 씁니다. 앱에 필요한 다른 기능(Object.assign, fetch 등)은 앱이 직접 폴리필합니다. 불러오기: `<script type="module" src="app.js">` + `<script nomodule src="vfunc.legacy.min.js">` + `<script nomodule src="app.es5.js">`.

## 코드 생성 규칙

1. 동적 마크업은 모두 `vf.html`(태그 템플릿)이나 `vf.tpl`로 만듭니다. 사용자 데이터를 HTML 문자열에 이어 붙이지 않습니다. `vf.unsafeHtml`은 직접 작성한 마크업에만, 왜 안전한지 주석과 함께 씁니다.
2. 이벤트는 `data-action` 셀렉터의 `delegates`나 id의 `events`로 겁니다. CSS 클래스로 고르지 않고, `onclick="…"`을 쓰지 않습니다.
3. 요소는 `data-ref`(`inst.refs.name`)나 `id`(`inst.ids.id`)로 찾습니다. 컴포넌트 루트 안쪽만 찾으므로, 루트 밖 요소는 `vf.$('#id')`로 찾습니다.
4. 디자인은 JS에 넣지 않습니다. 스크립트에 색·글꼴·간격을 쓰지 않습니다. CSS는 처음부터 새로 만드는 페이지에서도 색·크기·글꼴에 `var(--vf-*)` 토큰만 씁니다. `vfunc.tokens.css`(또는 프로젝트의 `tokens.css`)를 연결하고, hex·`rgb()`·`px` 값은 그 파일에만 둡니다.
5. `vf.*` 멤버와 네이티브 prototype을 고치지 않습니다. 확장은 `vf.use`로 `vf.ext`에 둡니다.
6. 클라이언트 라우트는 접근 제어가 아닙니다. 권한은 서버에서 검사합니다. 토큰은 store에 두지 말고 HttpOnly 쿠키를 권장합니다.
7. `eval`, `new Function`, 문자열 `setTimeout` 금지.

## vf.vfunc(options) — 컴포넌트 (`new` 있어도 없어도 됨)

옵션: `tag`('div'), `opts`(루트 속성. innerHTML/outerHTML/srcdoc와 문자열 on*은 거부), `innerHTML`(신뢰하는 초기 마크업), `render(state)` → vf.html 결과(`this`는 인스턴스), `replaceRoot`(기본 false: 루트는 `tag` 요소 — vf.attach는 대상 요소 자체 — 이고 마크업은 그 안쪽, true: 마크업의 첫 요소가 루트), `state`, `methods`, `events: [{ id?, eventType, onEvent? }]`(`id`는 루트 안 요소의 id. 없으면 루트 자체에 걸림), `delegates: [{ selector, eventType, onEvent? }]`, `childs: [인스턴스 | 노드 | { targetId, component }]`, `onEvent`, `onError`, `onMount(inst)`, `onUpdate(inst)`(렌더할 때마다 그 뒤. `render`가 없으면 상태가 바뀔 때마다 — 채택한 마크업에 상태를 여기서 반영), `onDestroy(inst)` — 훅은 state가 아니라 인스턴스를 받습니다.

이벤트 객체 `e`: `sender`(인스턴스), `event`, `eventType`, `target`(붙은 요소 또는 일치한 요소), `id`, `data`.

인스턴스: `$node`, `state`, `methods`, `ids`, `refs`, `setState(patch | (state) => patch)`(`vf.store`의 set처럼 얕은 병합, 한 tick에 한 번 렌더), `scheduleRefresh()`, `refresh()`, `mount(부모 또는 선택자)` → Promise, `destroy()`(`childs`의 인스턴스를 먼저 destroy, `onDestroy` 호출, 리스너 해제, 루트 제거 — `vf.attach`의 루트는 페이지에 남고, 컴포넌트가 그린 경우 안쪽만 비움), `toString()`(outerHTML). 바로 접근: `inst.count` ↔ `inst.state.count`(대입하면 렌더 예약), `inst.save()` → methods, `inst.btnSave` → ids. 우선순위는 state > methods > ids. 예약어는 바로 접근할 수 없습니다: $node, state, methods, ids, refs, isvfunc, setState, refresh, scheduleRefresh, mount, destroy, toString, valueOf, `_`로 시작하는 이름. 인스턴스에 직접 속성을 붙이지 않습니다(`_`로 시작하는 이름은 엔진 몫). 리스너 함수와 타이머는 클로저나 모듈 변수에 둡니다.

```js
const counter = vf.vfunc({
  state: { count: 0 },
  render: (s) => vf.html`<button type="button" data-action="inc">${s.count}</button>`,
  delegates: [{ selector: '[data-action="inc"]', eventType: 'click',
                onEvent: (e) => { e.sender.count++; } }]
});
counter.mount('#app');
```

refresh: 루트 안쪽을 교체하고, `childs`는 다시 옮겨 붙이며(상태 유지), `data-vf-keep="key"` 요소는 새로 만들지 않고 옮깁니다(서드파티 위젯은 여기에 두고 `onMount`에서 만들고 `onDestroy`에서 정리). 포커스와 커서는 같은 `id`, `data-ref`, `name`의 요소로, 없으면 같은 `data-action`의 같은 순서 요소로 돌아갑니다(입력 중 다시 그려지는 입력칸에는 이 중 하나를 줍니다). `onMount`는 `mount()`와 `vf.attach()`에서 호출되고, `childs`의 인스턴스에도 한 번(부모보다 먼저) 호출됩니다. `destroy()`는 `childs`의 인스턴스를 먼저 destroy합니다. 직접 만들어 mount한 인스턴스(목록 항목마다 만든 것 등)는 부모의 `onDestroy`에서 정리합니다. 가능하면 컨테이너에 위임을 모읍니다.

## vf.html과 관련 함수

- `vf.html\`…\``은 위치별로 처리합니다: 텍스트(이스케이프, 배열은 이어 붙임, vf.html 결과와 인스턴스는 마크업으로, null/undefined/false → ''), 따옴표 속성(이스케이프. 배열은 공백으로 이어 붙임, null/undefined → ''. `false` → ''이지만 `aria-*`/`data-*`에서는 boolean이 `"true"`/`"false"`로 남으므로 `aria-selected="${on}"`이 맞게 동작), URL 속성 href/src/action/formaction/poster/cite…(이스케이프 + `vf.safeUrl`), 태그 안은 속성 이름만(`<button ${disabled ? 'disabled' : ''}>`), 태그 이름은 script/style/iframe/svg… 제외.
- 거부: `on*` 속성, `srcdoc`, 따옴표 없는 값(`class=${x}`), `<script>`/`<style>` 내용, 함수. 값을 빼고 알리며, `vf.config({ strict: true })`면 예외를 던집니다(개발·테스트에서 권장).
- `vf.tpl('<a href="{url}">{label}</a>', data)` — 템플릿 리터럴 없이 같은 보호(ES5).
- `vf.esc(v)` → 문자열, `vf.nl2br(v)` → SafeHtml, `vf.safeUrl(u)` → http/https/mailto/tel/상대 경로 또는 '#', `vf.unsafeHtml(markup)`.

## vf.attach(target, options) — 퍼블리싱 HTML 제어

옵션은 `vf.vfunc`와 같습니다. 기존 요소가 루트가 되고 속성과 리스너가 유지됩니다. `render`/`innerHTML`이 없으면 마크업과 입력값도 그대로입니다. `render`가 있으면 `render`는 요소의 **안쪽만** 돌려줍니다(요소 태그를 다시 적지 않음). 요소 자신의 태그 안으로 파싱하므로 `<tbody>`에는 `tag` 없이 행을 그릴 수 있습니다. 상태에 따라 바뀌는 루트 속성은 `onMount`/`onUpdate`에서 설정합니다(`inst.$node.setAttribute(…)`). `replaceRoot: true`면 마크업의 첫 요소가 요소 자체를 대체합니다. 대상이 없으면 null. `destroy()`는 요소를 남깁니다(페이지의 요소이므로). 리스너를 해제하고 `render`/`innerHTML`로 그린 것만 지우므로 같은 요소에 다시 attach할 수 있습니다.

```js
vf.attach('#search', {
  delegates: [{ selector: '[data-action="submit"]', eventType: 'click',
                onEvent: (e) => search(vf.form.values(e.sender.$node)) }]
});
```

## 헬퍼

`vf.$(sel, root?)` → 첫 번째 요소 또는 null, `vf.$$(sel, root?)` → 요소 배열, `vf.el(tag, props?)`(opts와 같은 안전 규칙), `vf.node(html)`, `vf.frag(html)`, `vf.idMap(root)`, `vf.form.values(target, { skipPassword? })`(체크박스·라디오 → boolean, 다중 select → 배열), `vf.form.reset(target)`. 폼 값을 로그로 남기지 않습니다.

## SPA

```js
const r = vf.router({
  mode: 'hash',                                   // 또는 'history'(서버가 index.html을 돌려줌), base: '/app'
  routes: { '/': home, '/users/:id': (ctx) => user(ctx.params.id, ctx.query.tab), '/files/*': files },
  notFound: notFound, onChange: (ctx) => {}, linkSelector: 'a[data-link]', focus: 'main'
});
r.start(); r.go('/users/7'); r.replace('/'); r.current(); r.href('/x');
```
`go`는 `/`로 시작하는 앱 경로만 받습니다. 링크: `<a data-link href="#/users/7">`.

`const s = vf.store({ items: [] }); const off = s.subscribe(fn); s.set((st) => ({ items: st.items.concat(x) })); s.get('items');` — `set(patch | (state) => patch)`는 얕은 병합(다른 키는 유지), 키 없는 `get()`은 전체 상태, 구독 함수는 새 상태를 받고 한 tick에 한 번 알림을 받습니다.

## 다국어

```js
await vf.i18n.setup({ locales: ['ko', 'en'], fallback: 'en', messages: { en: { hello: 'Hello, {name}' } },
                      load: (l) => fetch(`./locales/${l}.json`).then((r) => r.json()), persist: true });
vf.t('hello', { name: 'Min' });                  // 평문. 복수형: { zero?, one, other }와 params.count
// locales/ko.json: { "nav": { "home": "홈" } } 또는 { "nav.home": "홈" } — vf.t('nav.home')가 둘 다 찾음
vf.i18n.subscribe(() => app.refresh());         // 다시 그리기는 여기서: 로케일이 준비된 뒤 호출됨
vf.i18n.set('ko');                               // Promise<locale>. 메시지를 먼저 불러옴. 바로 뒤에서 다시 그리지 않음
vf.i18n.apply();                                 // data-i18n, data-i18n-attr
// persist: true면 고른 로케일을 localStorage('vf.locale')에 저장하고 다음 setup()이 읽음 — 직접 쓰지 않음
// vf.i18n.add(locale, messages, { defaults: true }): 컴포넌트의 내장 기본 메시지. 앱 메시지보다 아래
vf.fmt.number(n); vf.fmt.currency(n, 'KRW'); vf.fmt.date(d); vf.fmt.relative(-3, 'day');
```

## 디자인 토큰 (선택: css/vfunc.tokens.css)

토큰 이름은 공개 API입니다: `--vf-color-primary|-hover|-active|-soft`, `--vf-color-on-primary`, `--vf-color-{success,warning,danger,info}`(+ `-soft`, `-text`), `--vf-color-bg|surface|surface-muted|overlay`, `--vf-color-text|text-muted|text-disabled|text-inverse`, `--vf-color-border|border-strong|focus`, `--vf-focus-ring`, `--vf-chart-1..8`, `--vf-shadow-1..3`, `--vf-radius-sm|md|lg|full`, `--vf-space-1..7`, `--vf-font-body|mono`, `--vf-font-size-xs|sm|md|lg|xl|2xl`, `--vf-font-weight-normal|strong`, `--vf-line-height`, `--vf-duration-fast|base`, `--vf-easing`, `--vf-z-dropdown|popover|drawer|modal|toast`. 이 목록에 없는 이름은 없습니다. 다크 테마는 OS를 따르고 `<html data-theme="light|dark">`로 강제합니다. 덮어쓸 때는 vfunc.tokens.css **다음에** 자기 CSS에서 선언합니다. 상태는 `aria-*`/`data-state`로 쓰고 CSS가 꾸밉니다. 라이브러리에 색이 필요할 때만 JS에서 getComputedStyle로 토큰을 읽습니다.

## update 플러그인 (dist/plugins/update.min.js → 전역 vfUpdate, ESM은 `import vfUpdate from 'vfunc/plugins/update'`)

`const update = vf.use(vfUpdate, { url: './version.json', current: APP_VERSION, policy: 'next-navigation' | 'prompt' | 'immediate', interval: 10, onAvailable: (info, apply) => {} })` → `vf.ext.update`(`check(force)`, `status()`, `navigated()`, `apply()`, `stop()`). version.json은 `{ "version": "1.0.3" }`이고 index.html과 함께 no-cache로 서빙합니다. 플러그인은 UI를 그리지 않고, 안내는 앱이 그립니다.

## shortcut 플러그인 (dist/plugins/shortcut.min.js → 전역 vfShortcut, ESM은 `import vfShortcut from 'vfunc/plugins/shortcut'`)

`const keys = vf.use(vfShortcut)` → `vf.ext.shortcut`: `const off = keys.add('mod+k', handler, { label, allowInInput: false, preventDefault: true })`, `keys.remove(combo, handler?)`, `keys.list()` → `[{ combo, label }]`(도움말 화면은 앱이 그림), `keys.destroy()`. `mod`는 Apple 기기에서 ⌘, 그 밖에서 Ctrl입니다. 키 이름은 KeyboardEvent.key를 따릅니다(`escape`, `enter`, `arrowup`, `?`). 입력칸 안의 키와 IME 조합 중인 키는 무시하고, 같은 조합은 가장 나중 것이 실행됩니다. 단축키용 document keydown 리스너를 직접 만들지 마세요.

## list 플러그인 (dist/plugins/list.min.js → 전역 vfList, ESM은 `import vfList from 'vfunc/plugins/list'`, 1.1.0부터)

행이 많고 몇 행만 자주 바뀌는 목록(갱신, 교환, 삭제)용입니다. render는 안쪽을 통째로 다시 그리지만 이 플러그인은 항목마다 요소 하나를 유지합니다. `const rows = vf.use(vfList).create('#tbody', { key: (item) => item.id, render: (item) => vf.html\`<tr>…</tr>\` })` → `rows.set(items)`(같은 키·같은 객체는 그대로, 새 객체는 그 행만 다시 그림, 순서가 바뀌면 옮기기만, 없어진 키는 제거), 객체를 제자리에서 고쳤으면 `rows.refresh(key?)`, `rows.items()`, `rows.element(key)`, `rows.destroy()`. 컨테이너는 행의 직접 부모이고 다른 요소를 넣지 않습니다. 컴포넌트 안에서는 `data-vf-keep`을 붙이고 `onMount`에서 만들거나, render 없는 `vf.attach` 대상을 씁니다. 행에는 `data-vf-key`가 붙으므로 `e.target.closest('[data-vf-key]')`로 항목을 찾습니다. `render`는 `vf.html`로 요소 하나를 돌려줍니다. `vf.vfListView`(vfunc-ui 1.2.0부터)는 이미 이렇게 행을 유지하므로, 플러그인은 목록을 직접 만들 때만 불러옵니다.

## 컴포넌트 (layer2: vfunc-ui)

클래스 없는 선택형 컴포넌트입니다. `vfunc.js` → `dist/vfunc-ui.js`(+ 그리드·차트는 `dist/vfunc-ui-data.js`, 한국어는 `dist/vfunc-ui.locale.ko.js`)를 불러오고, CSS는 토큰 다음에 `css/vfunc-ui.css`. ESM은 `import 'vfunc/ui'` / `import 'vfunc/ui/data'`가 `vf`에 멤버를 더합니다. 모든 이름·props·메서드는 ai/ko/components.md(catalog와 d.ts에서 생성)에 있습니다. 수고를 덜어 주는 곳에만 쓰고, 나머지는 HTML 그대로 써도 됩니다.

- `vf.vs*(props)`는 SafeHtml 마크업: `vf.html`·`render`에 그대로 넣습니다. `vf.vf*(props)`는 인스턴스: `.mount(el)` 또는 부모의 `childs`. 콜백은 `{ sender, event, data }`(`e.data`를 읽음), `getValue()` / `setValue(v)`(setValue는 onChange를 부르지 않음).
- 슬롯: `vs*`의 슬롯(vsCard body 등)은 마크업만 받습니다. 인스턴스를 넣으면 동작 없는 정적 사본이 됩니다. 살아 있는 컴포넌트는 `<div id="x"></div>`를 두고 내 컴포넌트의 `childs`에 `{ targetId: 'x', component }`를 넣습니다. vfTabs, vfAccordion, vfCarousel, vfPopover, vfModal, vfDrawer의 content 슬롯은 인스턴스도 받아 살려 둡니다.
- 공통 props: `id`, `ref`(data-ref), `action`(data-action), `className`, `describedBy`. 폼 컨트롤은 `name`, `value`, `disabled`, `readonly`, `required`에 `label` / `hint` / `error`를 주면 연결된 필드로 감쌉니다. 문자열 props는 이스케이프되니 마크업은 `vf.html`로 넘깁니다. 위임은 `data-action`에 걸고 `vf-*` 클래스에 걸지 않습니다.
- 입력: vsField, vsInput, vsTextarea, vsSelect, vsCheckbox, vsRadioGroup, vsSwitch, vsSlider, vsProgress, vsNumberInput/vfNumberInput, vsSearchInput/vfSearchInput, vsPasswordInput/vfPasswordInput, vsChipsInput/vfChipsInput, vsRating/vfRating, vsSelectButton/vfSelectButton, vsMaskedInput/vfMaskedInput, vsDatePicker/vfDatePicker, vsTimePicker/vfTimePicker, vfDateRangePicker.
- 표시: vsButton, vsButtonGroup, vsBadge, vsTag, vsAvatar, vsAlert, vsCard, vsDescriptions, vsStatCard, vsTimeline, vsEmptyState, vsSkeleton, vsSpinner, vsTooltip, vsListView/vfListView, vfCarousel.
- 내비게이션: vsBreadcrumb, vsPagination/vfPagination, vsTabs/vfTabs, vsAccordion/vfAccordion, vsStepper/vfStepper, vsSplitButton/vfSplitButton.
- 오버레이: vfModal, vfDrawer, vfConfirm(`const c = vf.vfConfirm({ title }); const ok = await c.open(); c.destroy();` — 또는 하나를 만들어 재사용), vfToast(알림 영역을 한 번 만들고 `toast.show({ message, variant })`), vfDropdown, vfPopover. document.body에 스스로 붙고 포커스를 가두며 닫으면 돌려줍니다.
- 데이터: vsTable, vsSparkline(코어 파일). vfunc-ui-data.js에 vfGrid(정렬, 페이징, 선택, `total`·onSort·onPage와 함께 `mode: 'server'`), vsChart/vfChart(bar, line, area, pie, donut, sparkline, 색은 `--vf-chart-*`).
- 어댑터(벤더 미포함. 벤더를 먼저 로드하고 `dist/vfunc-<kind>-<vendor>.js`): vfGridAg(AG Grid), vfGridTabulator, vfChartChartjs, vfChartEcharts — vfGrid / vfChart와 같은 props·메서드 + `lib`, `options`. `.instance`는 벤더 객체. 다른 라이브러리를 직접 감쌀 때는 ai/ko/prompt-integrate-third-party.md.
- 문구는 메시지 키(`emptyState.title`, `confirm.ok` 등)에서 옵니다. props나 `vf.i18n.add(locale, { … })`로 바꿉니다. 어댑터는 IE11을 지원하지 않고, 코어와 데이터 파일에는 `.legacy.min.js`가 있습니다.

## 흔한 실수

- 컴포넌트는 만드는 순간 렌더합니다. vf.t를 쓰는 컴포넌트는 `vf.i18n.setup()` 이후에 만드세요.
- `vf.i18n.set(...)` 바로 뒤에서 다시 그림(메시지를 아직 불러오는 중일 수 있음): `vf.i18n.subscribe`에서 다시 그립니다.
- 로케일이 바뀔 때 헤더만 refresh함: `vf.i18n.subscribe`에서 화면의 인스턴스를 모두 — 헤더와 현재 페이지 — refresh합니다.
- `data-vf-keep` 요소는 예전 속성도 그대로입니다. 바뀌는 속성은 onUpdate에서 갱신하세요.
- 항목별 버튼·체크박스에 `id`를 주면 refresh 뒤에도 포커스가 복원됩니다.
- 새 페이지 CSS의 원시 값(`color: #888`, `padding: 14px`): 토큰을 씁니다. 맞는 토큰이 없으면 값을 쓰지 말고 토큰 파일에 토큰을 추가합니다.
- 패널 전체에 `render`로 `vf.attach`하면 그 안의 정적 문구와 컨트롤까지 다시 만들어집니다. `render`는 내용이 바뀌는 가장 작은 요소(`#summary` 상자, `<tbody>`)에 붙이고, 나머지는 `render` 없이 채택합니다.
- CSP가 있으면 인라인 `style="…"`과 인라인 `<script>`를 쓸 수 없습니다. 파일로 두세요(보이기/숨기기는 `hidden` 속성).
- 표의 행은 table 안에서 파싱해야 합니다. `<tbody>`/`<tr>`을 렌더하는 `vf.vfunc`는 `tag: 'table'`(또는 `'tbody'`). `<tbody>`에 붙인 `vf.attach`는 따로 줄 것이 없습니다. `vf.node`/`vf.frag`는 `<div>`에서 파싱하므로 행에는 쓰지 않습니다.
- 데이터·로케일 주소는 모듈 기준(`new URL('./data/x.json', import.meta.url)`)으로 만들어야 버전 폴더 안에서도 맞습니다.
- `vf.attach` 인스턴스는 이미 페이지에 있습니다. `mount()`를 부르지 않습니다(요소를 자기 안에 넣게 됨). `mount()`는 `vf.vfunc` 인스턴스에만 씁니다.
- `vf.attach`와 `vf.$`의 대상도 훅으로 찾습니다: `'#id'`나 `'[data-ref="x"]'`. 클래스로 찾지 않습니다(`vf.$('.topbar__user')`는 디자인이 바뀌면 깨짐).
- `vf.html` 항목의 배열은 템플릿에 그대로 넣습니다(`${items}`). `.join('')`은 일반 문자열로 바꾸므로, 그것을 `innerHTML`에 넣으면 문자열로 만든 마크업이 됩니다. `render`로 다시 그리세요.
- JS에는 색 값을 쓰지 않습니다. 토큰이 없을 때를 대비한 대체 값(`value || '#1d4ed8'`)도 마찬가지입니다. 토큰 파일은 항상 로드됩니다.
- 누를 때마다 만들고 정리하지 않은 `vf.vfConfirm`은 메모리에 남습니다: `open()`의 답을 받은 뒤 `destroy()`하거나, 하나를 만들어 재사용합니다.
- 행이 수백 개 이상이고 행의 갱신·교환·삭제가 잦은 목록을 `render`로 그리기: 바뀔 때마다 모든 행을 다시 그립니다(몇 배에서 수십 배 느림). 이런 목록은 list 플러그인(vfList)을 씁니다. 짧은 목록은 `render`로 충분합니다.

## 예제, 스타터, 프롬프트 킷

layer1/examples/: 01 hello, 02 counter, 03 todo, 04 methods-refs, 05 composition, 06 attach-published-html, 07 form, 08 fetch-list, 09 spa-hash-router, 10 spa-app(SPA 표준 구조: app.js + store.js + api.js + pages/*.js), 11 css-tokens-theme, 12 with-bootstrap, 13 with-tailwind, 14 before-after-conversion(퍼블리싱 대시보드를 prompt-html-to-vfunc.md로 변환한 전후), 15 with-chartjs, 16 legacy-ie, 17 i18n, 18 extend-plugin, 19 design-apply, 20 merge-published, 21 cache-update.

layer2/examples/: dashboard(vfGrid / vfChart ↔ Tabulator·Chart.js 어댑터, 같은 props), settings-form(vs* 필드, `error`로 검증, vfConfirm, vfToast, 값은 컴포넌트 밖에), landing(HTML 페이지에 vsCard, vfCarousel, vfAccordion), legacy-ie(vfunc-all.legacy.min.js 위의 ES5), custom-component(공식 컴포넌트로 만든 내 vsPriceTag / vfCartLine, `vf`가 아닌 내 모듈에), gallery(모든 컴포넌트), third-party-custom(Leaflet L0, L1, L2).

layer1/starter/: 복사해서 쓰는 앱(라우터, store, 다국어, 토큰, update 플러그인, design/DESIGN.md, AGENTS.md, 버전 폴더 배포용 tools/release.mjs, 디자인 규칙·WCAG AA 토큰 대비 검사용 tools/design-check.mjs, deploy/ 캐시 설정). layer1/ai/{en,ko}/: AGENTS.template.md, 프롬프트(html-to-vfunc, spa-scaffold, migrate-from-react-vue, add-feature, debug, deploy-setup), anti-patterns.md, design/(DESIGN.template.md와 디자인 프롬프트 4종). layer2는 같은 ai/{en,ko}/ 폴더에 components.md(생성된 컴포넌트 목록), prompt-html-to-components.md(직접 만든 UI → vs* / vf*), prompt-integrate-third-party.md를 더합니다.

## 확장

`vf.use({ name: 'company', requires: '^1.0.0', install(vf, options) { return api; } }, options)` → `vf.ext.company`. `vf` 루트에 멤버를 추가하지 않습니다.

## 더 보기

- 타입: `types/vfunc.d.ts`(ES 모듈), `types/global.d.ts`(스크립트 빌드의 전역 `vf`)
- 전체 레퍼런스: llms-full.txt · 한국어 문서: 사이트 · 확장: EXTENDING.md · 보안: SECURITY.md