# vfunc.js

> vfunc.js is a no-build vanilla JavaScript UI library (Apache-2.0). No virtual DOM: components render with innerHTML, events use delegation, and elements are reached through `data-ref`. Idea: keep your HTML as it is and use vfunc only where you need control. One global `vf`.

For vfunc.js 1.0. The full reference is llms-full.txt (this file + the website guide and API reference + the type declarations); this file keeps only what is needed to write correct code. Korean: llms.ko.txt.

## Load

- Script tag: `<script src="https://cdn.jsdelivr.net/npm/vfunc@1.2.0/dist/vfunc.min.js" integrity="sha384-yTR0o8US3nk+D1XIBAsv1O/lMFA5tV3V021xPo8yxyqnBNSxi1rqINVvBOykAEkK" crossorigin="anonymous"></script>` → global `vf`. Pin the exact version and add SRI in production; the integrity value differs per version and file (this one is 1.2.0 vfunc.min.js). `dist/vfunc.js` is the development build with warnings.
- ES module: `import vf from 'vfunc'` or `import { vfunc, html, router } from 'vfunc'`; a copied file works the same (`import vf from './lib/vfunc.esm.min.js'`). The ES modules never touch `window.vf`.
- IE11 / Edge IE mode: `dist/vfunc.legacy.min.js` (same API; includes only a Promise polyfill). The app code must be ES5: no arrow functions, const/let, template literals or classes; use `vf.tpl('<b>{name}</b>', data)` instead of vf.html template literals. Polyfill anything else the app needs (Object.assign, fetch, …) yourself. Load pattern: `<script type="module" src="app.js">` + `<script nomodule src="vfunc.legacy.min.js">` + `<script nomodule src="app.es5.js">`.

## Rules for generated code

1. Build every dynamic markup with `vf.html` (tagged template) or `vf.tpl`. Never concatenate user data into HTML strings. `vf.unsafeHtml` only for markup you wrote, with a comment explaining why it is safe.
2. Bind events with `delegates` on `data-action` selectors, or `events` on ids. Never select by CSS class; never write `onclick="…"`.
3. Reach elements with `data-ref` (`inst.refs.name`) or `id` (`inst.ids.id`) — inside the component's root only; use `vf.$('#id')` for elements outside it.
4. Keep design out of JS: no colors, fonts or spacing in scripts. CSS — also in a page you write from scratch — uses only `var(--vf-*)` tokens for colors, sizes and fonts: link `vfunc.tokens.css` (or the project's `tokens.css`); hex, `rgb()` and `px` values live only in that file.
5. Never modify `vf.*` members or native prototypes. Extensions go to `vf.ext` through `vf.use`.
6. Client routes are not access control; the server checks permissions. Keep tokens out of the store; prefer HttpOnly cookies.
7. No `eval`, `new Function`, or string `setTimeout`.

## vf.vfunc(options) — a component (with or without `new`)

Options: `tag` ('div'), `opts` (root properties; innerHTML/outerHTML/srcdoc and string on* refused), `innerHTML` (trusted initial markup), `render(state)` → vf.html result (`this` is the instance), `replaceRoot` (default false: the root is a `tag` element — for vf.attach the target itself — and the markup is its inside; true: the first element of the markup is the root), `state`, `methods`, `events: [{ id?, eventType, onEvent? }]` (`id` of an element inside the root; without `id` the listener is on the root itself), `delegates: [{ selector, eventType, onEvent? }]`, `childs: [instance | node | { targetId, component }]`, `onEvent`, `onError`, `onMount(inst)`, `onUpdate(inst)` (after each render; without `render`, after each state change — write the state to the adopted markup there), `onDestroy(inst)` — the hooks get the instance, not the state.

Event object `e`: `sender` (instance), `event`, `eventType`, `target` (bound or matched element), `id`, `data`.

Instance: `$node`, `state`, `methods`, `ids`, `refs`, `setState(patch | (state) => patch)` (shallow merge like `vf.store`'s set; batched, one render per tick), `scheduleRefresh()`, `refresh()`, `mount(parentOrSelector)` → Promise, `destroy()` (destroys the instances in `childs`, calls `onDestroy`, releases listeners and removes the root — a `vf.attach` root stays in the page, emptied if the component drew it), `toString()` (outerHTML). Shortcuts: `inst.count` ↔ `inst.state.count` (assignment schedules a render), `inst.save()` → methods, `inst.btnSave` → ids; priority state > methods > ids. Reserved names cannot be shortcuts: $node, state, methods, ids, refs, isvfunc, setState, refresh, scheduleRefresh, mount, destroy, toString, valueOf, names starting with `_`. Do not add your own properties to an instance (names starting with `_` belong to the engine): keep listener functions and timers in a closure or module variable.

```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: the root's content is replaced; `childs` are moved back (their state kept); `data-vf-keep="key"` elements are moved, not rebuilt (third-party widgets live there; create them in `onMount`, release them in `onDestroy`); focus and caret return to the element with the same `id`, `data-ref` or `name`, else the same `data-action` at the same position (give inputs that re-render while typing one of these). `onMount` runs for `mount()` and `vf.attach()`, and once for the instances in `childs` (before their parent). `destroy()` destroys the instances in `childs` first. Instances you create and mount yourself (for example per list item) are yours to destroy in the parent's `onDestroy`; prefer delegation on containers.

## vf.html and friends

- `vf.html\`…\`` escapes by position: text (escaped; arrays joined; vf.html results and instances inserted as markup; null/undefined/false → ''), quoted attribute (escaped; arrays joined with spaces; null/undefined → ''; `false` → '' except in `aria-*`/`data-*`, where booleans stay `"true"`/`"false"`, so `aria-selected="${on}"` works), URL attributes href/src/action/formaction/poster/cite… (escaped + `vf.safeUrl`), inside a tag only bare names (`<button ${disabled ? 'disabled' : ''}>`), tag names except script/style/iframe/svg….
- Refused: `on*` attributes, `srcdoc`, unquoted values (`class=${x}`), content of `<script>`/`<style>`, functions. The value is dropped and reported; `vf.config({ strict: true })` throws instead (use in development and tests).
- `vf.tpl('<a href="{url}">{label}</a>', data)` — the same protection without template literals (ES5).
- `vf.esc(v)` → string, `vf.nl2br(v)` → SafeHtml, `vf.safeUrl(u)` → http/https/mailto/tel/relative or '#', `vf.unsafeHtml(markup)`.

## vf.attach(target, options) — control published HTML

Options are the same as `vf.vfunc`. The existing element becomes the root and keeps its attributes and listeners. Without `render`/`innerHTML` its markup and input values stay too. With `render`, `render` returns **only the inside** of the element (do not repeat its tag); it is parsed as content of the element's own tag, so rows can be rendered into a `<tbody>` without `tag`. Attributes of the root that depend on state are set in `onMount`/`onUpdate` (`inst.$node.setAttribute(…)`). `replaceRoot: true` replaces the element with the first element of the markup instead. Returns null if not found. `destroy()` keeps the element (it belongs to the page): listeners are released and what `render`/`innerHTML` drew is removed, so the same element can be attached again.

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

## Helpers

`vf.$(sel, root?)` → the first match or null, `vf.$$(sel, root?)` → an array of matches, `vf.el(tag, props?)` (same safety rules as opts), `vf.node(html)`, `vf.frag(html)`, `vf.idMap(root)`, `vf.form.values(target, { skipPassword? })` (checkbox/radio → boolean, multiple select → array), `vf.form.reset(target)`. Never log form values.

## SPA

```js
const r = vf.router({
  mode: 'hash',                                   // or 'history' (server returns 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` accepts only app paths starting with "/". Links: `<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)` shallow-merges the patch (other keys stay); `get()` without a key returns the whole state; subscribers receive the new state, one notification per tick.

## i18n

```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' });                  // plain text; plural: { zero?, one, other } with params.count
// locales/en.json: { "nav": { "home": "Home" } } or { "nav.home": "Home" } — vf.t('nav.home') finds either
vf.i18n.subscribe(() => app.refresh());         // re-render here: subscribers run after the locale is ready
vf.i18n.set('ko');                               // Promise<locale>; loads messages first. Do not re-render right after it
vf.i18n.apply();                                 // data-i18n, data-i18n-attr
// persist: true stores the choice in localStorage ('vf.locale') and setup() reads it next time — do not write it yourself
// vf.i18n.add(locale, messages, { defaults: true }): built-in component defaults, below the app's messages
vf.fmt.number(n); vf.fmt.currency(n, 'KRW'); vf.fmt.date(d); vf.fmt.relative(-3, 'day');
```

## Design tokens (optional css/vfunc.tokens.css)

Token names are public 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`. There are no other names. Dark theme follows the OS; `<html data-theme="light|dark">` forces one. Override tokens in your CSS after vfunc.tokens.css. Put state in `aria-*` / `data-state` and let CSS style it; read a token in JS with getComputedStyle only when a library needs a color.

## Update plugin (dist/plugins/update.min.js → global 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` with `check(force)`, `status()`, `navigated()`, `apply()`, `stop()`. version.json is `{ "version": "1.0.3" }`; serve it and index.html with `Cache-Control: no-cache`. The plugin draws no UI; the app shows the prompt.

## Shortcut plugin (dist/plugins/shortcut.min.js → global 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 }]` for your own help screen, `keys.destroy()`. `mod` is ⌘ on Apple devices and Ctrl elsewhere; key names follow KeyboardEvent.key (`escape`, `enter`, `arrowup`, `?`). Keys typed in inputs and during IME composition are ignored; the newest shortcut of a combo wins. Do not write your own document keydown listener for shortcuts.

## List plugin (dist/plugins/list.min.js → global vfList; ESM `import vfList from 'vfunc/plugins/list'`; since 1.1.0)

For long lists where a few rows change often (update, swap, remove): a render redraws the whole inside, this keeps one element per item. `const rows = vf.use(vfList).create('#tbody', { key: (item) => item.id, render: (item) => vf.html\`<tr>…</tr>\` })` → `rows.set(items)` (same key and same object: kept; new object: only that row is drawn; new order: moved; missing: removed), `rows.refresh(key?)` after an in-place change, `rows.items()`, `rows.element(key)`, `rows.destroy()`. The container is the direct parent of the rows and holds nothing else; inside a component mark it `data-vf-keep` and create the list in `onMount`, or use a `vf.attach` target without render. Rows carry `data-vf-key`: find the item with `e.target.closest('[data-vf-key]')`. `render` returns one element built with `vf.html`. `vf.vfListView` (vfunc-ui 1.2.0+) already keeps its rows this way; load the plugin only for lists you build yourself.

## Components (layer 2: vfunc-ui)

Optional components without classes. Load `vfunc.js` → `dist/vfunc-ui.js` (+ `dist/vfunc-ui-data.js` for the grid and charts, + `dist/vfunc-ui.locale.ko.js` for Korean) and `css/vfunc-ui.css` after the tokens; ESM `import 'vfunc/ui'` / `import 'vfunc/ui/data'` add the members to `vf`. Every name, prop and method: ai/en/components.md (generated from the catalog and d.ts). Use a component where it saves work; plain HTML stays fine.

- `vf.vs*(props)` returns SafeHtml markup: put it in `vf.html` / `render` as is. `vf.vf*(props)` returns an instance: `.mount(el)` or a parent's `childs`; callbacks get `{ sender, event, data }` (read `e.data`); `getValue()` / `setValue(v)` (setValue never calls onChange).
- Slots: a `vs*` slot (vsCard body, …) takes markup only — an instance there becomes a static copy; for a live one leave `<div id="x"></div>` and add `{ targetId: 'x', component }` to your `childs`. The content slots of vfTabs, vfAccordion, vfCarousel, vfPopover, vfModal and vfDrawer also take an instance and keep it alive.
- Common props: `id`, `ref` (data-ref), `action` (data-action), `className`, `describedBy`; form controls add `name`, `value`, `disabled`, `readonly`, `required`, and `label` / `hint` / `error` wrap them in a linked field. String props are escaped; pass markup with `vf.html`. Delegate on `data-action`, never on the `vf-*` classes.
- Input: 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.
- Display: vsButton, vsButtonGroup, vsBadge, vsTag, vsAvatar, vsAlert, vsCard, vsDescriptions, vsStatCard, vsTimeline, vsEmptyState, vsSkeleton, vsSpinner, vsTooltip, vsListView/vfListView, vfCarousel.
- Navigation: vsBreadcrumb, vsPagination/vfPagination, vsTabs/vfTabs, vsAccordion/vfAccordion, vsStepper/vfStepper, vsSplitButton/vfSplitButton.
- Overlay: vfModal, vfDrawer, vfConfirm (`const c = vf.vfConfirm({ title }); const ok = await c.open(); c.destroy();` — or create one and reuse it), vfToast (create one region, then `toast.show({ message, variant })`), vfDropdown, vfPopover. They add themselves to document.body, trap focus and return it on close.
- Data: vsTable, vsSparkline (core file); vfGrid (sorting, paging, selection, `mode: 'server'` with `total`, onSort, onPage), vsChart/vfChart (bar, line, area, pie, donut, sparkline; colors from `--vf-chart-*`) in vfunc-ui-data.js.
- Adapters (vendor not bundled; load the vendor, then `dist/vfunc-<kind>-<vendor>.js`): vfGridAg (AG Grid), vfGridTabulator, vfChartChartjs, vfChartEcharts — the same props and methods as vfGrid / vfChart plus `lib` and `options`; `.instance` is the vendor object. Your own wrapper for another library: ai/en/prompt-integrate-third-party.md.
- Text comes from message keys (`emptyState.title`, `confirm.ok`, …): override with props or `vf.i18n.add(locale, { … })`. No IE11 for the adapters; the core and data files have `.legacy.min.js` builds.

## Common mistakes

- A component renders when created: create components that use vf.t after `vf.i18n.setup()` resolves.
- Re-rendering right after `vf.i18n.set(...)` (the messages may still be loading): re-render in `vf.i18n.subscribe`.
- Refreshing only the header on a locale change: in `vf.i18n.subscribe`, refresh every instance on the screen — the header and the current page.
- A `data-vf-keep` element keeps its old attributes; update changing attributes in `onUpdate`.
- Give per-item buttons and checkboxes an `id` so focus survives a refresh.
- Raw values in a new page's CSS (`color: #888`, `padding: 14px`): use tokens; if one is missing, add it to the token file instead of writing the value.
- `vf.attach` with `render` on a whole panel rebuilds its static text and controls: attach `render` to the smallest element whose content changes (the `#summary` box, the `<tbody>`) and adopt the rest without `render`.
- With a CSP, no inline `style="…"` or inline `<script>`: use files (show/hide with the `hidden` attribute).
- Table rows must be parsed inside a table: a `vf.vfunc` that renders `<tbody>`/`<tr>` uses `tag: 'table'` (or `'tbody'`); `vf.attach` on a `<tbody>` needs nothing. `vf.node` / `vf.frag` parse in a `<div>`, so not for rows.
- Resolve data and locale URLs from the module (`new URL('./data/x.json', import.meta.url)`), so they still work inside a version folder.
- A `vf.attach` instance is already in the page: never call `mount()` on it (that puts the element inside itself). `mount()` is for `vf.vfunc` instances only.
- The target of `vf.attach` and `vf.$` is found like any hook: `'#id'` or `'[data-ref="x"]'`, never a class (`vf.$('.topbar__user')` breaks when the design changes).
- A list of `vf.html` items goes into the template as is (`${items}`); `.join('')` turns it into a plain string, and putting that in `innerHTML` is string-built markup. Re-render with `render` instead.
- No color literal in JS, not even as a fallback when a token is missing (`value || '#1d4ed8'`): the token file is always loaded.
- A `vf.vfConfirm` created on every click and never destroyed stays in memory: `destroy()` it after `open()` resolves, or create one and reuse it.
- A long list (hundreds of rows or more) whose rows are updated, swapped or removed often, drawn by `render`: every change redraws all rows (several to tens of times slower). Use the list plugin (vfList) for it; short lists are fine with `render`.

## Examples, starter and prompt kit

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 (standard SPA structure: app.js + store.js + api.js + pages/*.js), 11 css-tokens-theme, 12 with-bootstrap, 13 with-tailwind, 14 before-after-conversion (a published dashboard converted with 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 ↔ the Tabulator and Chart.js adapters, same props), settings-form (vs* fields, validation with `error`, vfConfirm, vfToast, values kept outside the component), landing (plain HTML page with vsCard, vfCarousel, vfAccordion), legacy-ie (ES5 on vfunc-all.legacy.min.js), custom-component (your own vsPriceTag / vfCartLine from official components, in your module, not on `vf`), gallery (every component), third-party-custom (Leaflet at L0, L1, L2).

layer1/starter/: a copyable app (router, store, i18n, tokens, update plugin, design/DESIGN.md, AGENTS.md, tools/release.mjs for version-folder releases, tools/design-check.mjs for the design rules and WCAG AA token contrast, deploy/ cache headers). layer1/ai/{en,ko}/: AGENTS.template.md, prompts (html-to-vfunc, spa-scaffold, migrate-from-react-vue, add-feature, debug, deploy-setup), anti-patterns.md, design/ (DESIGN.template.md and four design prompts). Layer 2 adds to the same ai/{en,ko}/ folders: components.md (generated component list), prompt-html-to-components.md (hand-written UI → vs* / vf*), prompt-integrate-third-party.md.

## Extensions

`vf.use({ name: 'company', requires: '^1.0.0', install(vf, options) { return api; } }, options)` → `vf.ext.company`. Never add members to the `vf` root.

## Optional

- Types: `types/vfunc.d.ts` (ES modules), `types/global.d.ts` (global `vf` of the script build).
- Full reference: llms-full.txt · Extending: EXTENDING.md · Security: SECURITY.md