# vfunc.js — full reference for LLMs (v1.2.0)

> Generated by build/llms.mjs from llms.txt, the website pages (site/content/en), layer1/types/*.d.ts and layer2/ai/en/components.md. Do not edit.
> build/llms.mjs가 생성합니다. 직접 고치지 마세요. 한국어 문서는 사이트(site/content/ko)에 있습니다.

---

# Part 1 — Summary and rules (llms.txt)


> 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

---

# Part 2 — Guide and API reference (website)

## Getting started

### Start with one file

Create an HTML file and load vfunc. There is no build step.

```html
<script src="https://cdn.jsdelivr.net/npm/vfunc@1.2.0/dist/vfunc.min.js"
        integrity="sha384-yTR0o8US3nk+D1XIBAsv1O/lMFA5tV3V021xPo8yxyqnBNSxi1rqINVvBOykAEkK" crossorigin="anonymous"></script>
```

```html
<div id="app"></div>
<script src="https://cdn.jsdelivr.net/npm/vfunc@1.2.0/dist/vfunc.js"></script>
<script src="./app.js"></script>
```

```js
// app.js
const hello = vf.vfunc({
  state: { name: 'vfunc' },
  render: (s) => vf.html`
    <p>Hello, <strong>${s.name}</strong>!</p>
    <input id="name" value="${s.name}" data-action="rename">`,
  delegates: [{ selector: '[data-action="rename"]', eventType: 'input',
                onEvent: (e) => { e.sender.name = e.target.value; } }]
});
hello.mount('#app');
```

- Develop with `vfunc.js` (the development build): it explains mistakes in the console. In production use `vfunc.min.js` with SRI, as above.
- Use exact versions in URLs (`vfunc@1.2.0`). Ranges such as `vfunc@1` are cached by the CDN and pick up new versions late.
- Open pages through a static server, not `file://`: `python -m http.server 8080`.

### As an ES module

```js
import vf from 'vfunc';                       // npm i vfunc
import { vfunc, html, router } from 'vfunc';  // named imports work too
```

The ES modules never create a global `window.vf`. Bundlers pick the minified file without warnings for production builds (the `production` condition in `exports`).

### Start from the starter

A copyable app with a router, shared state, Korean/English, themes and release tools.

```bash
npx degit vidkid-indy/vfunc/layer1/starter my-app
cd my-app
python -m http.server 8080
```

| Path | What |
|---|---|
| `app.js` | messages, layout, router, update plugin — one route per new screen |
| `pages/*.js` | one `(ctx, router) => component` function per screen |
| `store.js` · `api.js` | shared state and the functions that change it · every server call |
| `locales/{en,ko}.json` | messages |
| `styles/tokens.css` | design tokens (derived from `design/DESIGN.md`) |
| `AGENTS.md` | rules read by AI tools (fill in section 0) |
| `tools/release.mjs`, `deploy/` | version-folder releases and server cache settings |

### Read next

- [Core concepts](guide.md): components, state, events, existing HTML, safe HTML
- [SPA](spa.md): router, store, i18n
- [Examples](examples.md): 21 of them, each with a source link

## Core concepts

### Components

`vf.vfunc(options)` creates a component, with or without `new`.

```js
const box = vf.vfunc({
  tag: 'section',                         // root element, default 'div'
  state: { open: false },                 // state
  render: (s) => vf.html`<button type="button" data-action="toggle"
    aria-expanded="${s.open ? 'true' : 'false'}">Details</button>
    ${s.open ? vf.html`<p data-ref="body">More text</p>` : ''}`,
  methods: { close() { this.open = false; } },
  delegates: [{ selector: '[data-action="toggle"]', eventType: 'click',
                onEvent: (e) => { e.sender.open = !e.sender.open; } }]
});
box.mount('#app');
```

- **State**: `box.open` is `box.state.open`. Assigning it or calling `setState({…})` schedules a render; changes in the same tick render once.
- **Methods** are bound to the instance: call `box.close()`, or pass it around as a callback.
- **Elements**: `data-ref="body"` → `box.refs.body`, `id="save"` → `box.ids.save`. Only inside the component's root; find elements outside it with `vf.$('#id')`.

### Events

| Kind | Use for |
|---|---|
| `delegates: [{ selector, eventType, onEvent }]` | one listener on the root, matched with `closest(selector)` inside the root — one for every row of a list |
| `events: [{ id, eventType, onEvent }]` | directly on one element (scroll, focus) |

The event object is `{ sender, event, eventType, target, id, data }`. **Hang selectors on `data-action`, `data-ref` or `id` only.** Selectors on CSS classes break when the design changes.

### Existing HTML — `vf.attach`

The core idea of vfunc: keep the publisher's HTML and add behaviour.

```js
// Without render: adopt the element as it is (markup, typed values and styles stay)
vf.attach('#search', {
  delegates: [{ selector: '[data-action="search"]', eventType: 'submit',
                onEvent: (e) => { e.event.preventDefault(); run(vf.form.values(e.sender.$node)); } }]
});

// With render: the element stays, render fills its inside (areas that change with data)
const results = vf.attach('#results', { state: { items: [] }, render: (s) => vf.html`…` });
```

### Safe HTML — `vf.html`

`vf.html` looks at **where** each value lands.

| Position | Handling |
|---|---|
| element content `<p>${x}</p>` | HTML-escaped; arrays joined; `vf.html` results inserted as markup |
| quoted attribute `title="${x}"` | escaped; `false`/`null` empty, but `aria-*`/`data-*` keep `"true"`/`"false"` |
| URL attribute `href`, `src`, `action` … | escaped + `vf.safeUrl` (`javascript:` refused) |
| inside a tag `<button ${x}>` | bare attribute names such as `disabled` only |
| `on*` attributes, `<script>`, unquoted attributes | **refused**: the value is dropped and reported (an error with `vf.config({ strict: true })`) |

- In ES5 code without template literals, `vf.tpl('<a href="{url}">{label}</a>', data)` gives the same protection.
- `vf.unsafeHtml(markup)` is for markup **you wrote** (icon SVG), with a comment explaining why it is safe.

### Lifecycle and third-party widgets

| Hook | When | Do |
|---|---|---|
| `onMount` | right after `mount()` / `vf.attach()` put it in the page (instances in `childs`: once, before their parent) | create charts and editors, load data, subscribe |
| `onUpdate` | after every render (without `render`, after every state change) | push the new state into widgets or adopted markup |
| `onDestroy` | in `destroy()`, after the instances in `childs` are destroyed | release widgets, timers, subscriptions |

Mark elements that must survive renders (a chart canvas) with `data-vf-keep="chart"`: the element is moved, not rebuilt. See [example 15](examples.md).

### Children and slots

`childs: [{ targetId: 'main', component: child }]` puts a child into the element with `id="main"`, and moves it back after every parent render so its state survives. Child instances get `onMount` when the parent enters the page and are destroyed with the parent. Instances you create and attach yourself, outside `childs`, are yours to `destroy()` in the parent's `onDestroy`.

### Forms

`vf.form.values(form)` reads every input with an id as `{ id: value }` (checkboxes as booleans). `vf.form.reset(form)` clears them. Never log form values; leave passwords out with `{ skipPassword: true }` when you show them.

### Common mistakes

- Building strings without `vf.html` in `render` → nothing is escaped.
- One component per list row → use one delegated listener.
- `setState` on every keystroke → store the value, render on submit.
- Rendering table rows without `tag: 'table'` → the `<tr>` elements disappear.
- Believing client routes protect anything → check permissions on the server.

## SPA: router, store, i18n

### App structure

```
index.html       <div id="app"> + <script type="module" src="app.js">
app.js           layout + router + page switching (the only place that knows every page)
store.js         vf.store and the functions that change it
api.js           every server call
pages/*.js       one (ctx, router) => component per screen
components/*.js  reusable parts
```

The [starter](getting-started.md#start-from-the-starter) and example 10 use this structure.

### Router — `vf.router`

```js
const router = vf.router({
  mode: 'hash',                                 // default: any static server, IE too
  routes: {
    '/': (ctx) => show(homePage(ctx, router)),
    '/orders/:id': (ctx) => show(orderPage(ctx.params.id, ctx.query.tab))
  },
  notFound: (ctx) => show(notFoundPage(ctx)),
  onChange: (ctx) => { document.title = ctx.route || 'Not found'; },
  focus: '#view'                                // focus after navigation (screen readers)
});
router.start();
```

- Links are ordinary `<a data-link href="${router.href('/orders/7')}">`; the router intercepts them. New windows, downloads and external addresses are left to the browser.
- `router.go(path)` accepts only app paths starting with `/`; `javascript:` or other sites are refused.
- `history` mode needs a server that returns `index.html` for every app path.
- `destroy()` the previous page when switching: its listeners and subscriptions are released.

> Client routes are not access control. Hiding an admin screen protects nothing; check permissions on the server.

### Shared state — `vf.store`

```js
export const cart = vf.store({ items: [] });
export function add(item) { cart.set((s) => ({ items: s.items.concat(item) })); }

// in a component
onMount: (inst) => { off = cart.subscribe((s) => inst.setState({ count: s.items.length })); },
onDestroy: () => off()
```

- Several `set` calls in one tick notify subscribers once.
- Change state only through the functions in `store.js`. Keep secrets such as tokens out (sessions belong in HttpOnly cookies).

### i18n — `vf.i18n`, `vf.t`, `vf.fmt`

```js
await vf.i18n.setup({
  locales: ['ko', 'en'], fallback: 'en',
  load: (l) => fetch(new URL('./locales/' + l + '.json', import.meta.url)).then((r) => r.json()),
  persist: true
});
vf.t('cart.items', { count: 3 });       // picks { zero, one, other }
vf.fmt.currency(12900, 'KRW');           // Intl formatting in the current locale
vf.i18n.apply();                         // translates data-i18n / data-i18n-attr in published HTML
```

- A locale is loaded only when it passes both the allow-list (`locales`) and a format check.
- `vf.t` returns plain text that `vf.html` escapes; `data-i18n` also inserts text only.
- **A component renders when it is created.** Create components that use `vf.t` after `setup()` resolves.
- On a locale change, re-render in `vf.i18n.subscribe(() => …)` and call `apply()` again. `<html lang>` follows automatically.
- `vf.i18n.set(locale)` returns a Promise. It loads the messages first and then calls the subscribers, so do not re-render right after `set()`: re-render in `subscribe`.
- `persist: true` stores the chosen locale in `localStorage` (key `vf.locale`, or the string you pass) and the next `setup()` reads it. Do not store it yourself.

## Design: tokens and DESIGN.md

Whenever the design arrives, the logic should not change. Example 19 puts three skins on one app without changing a line of JavaScript.

### Separation rules

1. Behaviour on `data-action` · `data-ref` · `id`; looks on classes (`<block>__<element>`).
2. State as `aria-*` or `data-state`; CSS styles those attributes.
3. No colors, fonts, spacing or shadows in JavaScript.
4. CSS reads only `var(--vf-*)` tokens; raw values live only in the token file.
5. `DESIGN.md` is the source; the token file is derived from it.
6. A design task never changes logic.

### Tokens — `css/vfunc.tokens.css`

An optional, neutral skin with light and dark themes. Token names are public API.

```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/vfunc@1.2.0/css/vfunc.tokens.css">
<link rel="stylesheet" href="./brand.css">   <!-- override tokens here -->
```

| Group | Examples |
|---|---|
| Colors | `--vf-color-primary`, `--vf-color-surface`, `--vf-color-text-muted`, `--vf-color-danger-soft` |
| Charts | `--vf-chart-1` … `--vf-chart-8` |
| Shape | `--vf-space-1..7`, `--vf-radius-md`, `--vf-shadow-2` |
| Type | `--vf-font-body`, `--vf-font-size-md`, `--vf-font-weight-strong` |

- The dark theme follows the OS; `<html data-theme="dark">` forces it. Apply a saved theme before the first paint from an external script in `<head>`.
- The main text and background pairs of the default skin pass WCAG AA in light and dark.
- When a library needs a color (charts), read the token: `getComputedStyle(document.documentElement).getPropertyValue('--vf-chart-1')`.

### The DESIGN.md workflow

| Situation | Do |
|---|---|
| Design material in any format | `prompt-design-normalize` → a standard `DESIGN.md` |
| New app with a design | `prompt-new-app-with-design`: tokens and CSS first, then code |
| Design arrives later | `prompt-apply-design`: tokens and CSS only, confirm no JS change, `--scope` per screen |
| Published HTML arrives for finished screens | `prompt-merge-published-html`: replace only the render markup, with a hook mapping table |

The prompts and the `DESIGN.md` template are in [Working with AI](ai.md). With Tailwind, map `@theme` onto the tokens (example 13).

### Design check — `design-check`

The starter's `tools/design-check.mjs` checks the rules above with no build and no dependency (optional). It exits with code 1 when something is wrong, so it fits before a commit or in CI.

```bash
node tools/design-check.mjs          # this project
node tools/design-check.mjs ../other --tokens css/vfunc.tokens.css
```

- Raw colors outside token declarations (`--x: …`), in CSS and JS
- JS selectors that find elements by class (`selector: '.x'`, `querySelector('.x')`, `closest`, `vf.$`)
- `vf.unsafeHtml` without a comment saying why
- Token contrast (WCAG AA): 4.5:1 for text, 3:1 for the focus color, light and dark; the app's own `:root` overrides count.
- Where a finding is intended, add `design-check-ignore` to the line (or `design-check-ignore-file` to the file) with the reason.

## Extensions, plugins, IE

### Extension rules

Extend vfunc through its public API, never by editing its source. Then your extensions keep working when vfunc is updated.

| Level | How |
|---|---|
| Settings | `vf.config({ strict: true })`, messages, tokens |
| Styles | override `--vf-*` after the token file |
| Composition | functions that create components, `childs`, your own components around the official [components](components.md) (below) |
| Third-party | `onMount` + `data-vf-keep` + `onDestroy`; levels L0, L1, L2 in [Third-party integration](third-party.md) |
| Plugins | `vf.use(plugin)` → `vf.ext.<name>` |

- Official `vf.*` members are read-only, and extensions do not add members to the `vf` root.
- Never patch native prototypes (`Event.prototype` and the like).

### Your own components

Components you build from the official ones read like the rest of your code when they keep the layer 2 rules. Sample: `layer2/examples/custom-component`.

```js
// shop-ui.js — your module, not the vf root
export function vsPriceTag({ amount, was, currency = 'USD' }) {
  const off = was > amount ? Math.round((1 - amount / was) * 100) : 0;
  return vf.html`<span class="price-tag">${vf.fmt.currency(amount, currency)}${
    off ? vf.vsBadge({ label: '-' + off + '%', variant: 'danger' }) : ''}</span>`;
}
```

- `vs*` returns SafeHtml built with `vf.html`; `vf*` returns an instance with `getValue()` / `setValue(v)`. Callbacks receive `{ sender, event, data }`.
- Put the official `vf*` you use inside in `childs` (`{ targetId, component }`): they survive your re-renders and are destroyed with you.
- Hooks on `id`, `data-ref`, `data-action`; your own block class names (`vf-*` is ours); tokens only in CSS.
- To share them across apps, bundle them as a `vf.ext.<name>` plugin.

### Plugins — `vf.use`

```js
vf.use({
  name: 'company', version: '1.0.0', requires: '^1.0.0',
  install(vf, options) { return { toast: (message) => { /* … */ } }; }
}, { duration: 3000 });
vf.ext.company.toast('saved');
```

### Official plugin — `vf.ext.update`

Brings new releases to places without a reload button (web views, kiosks, installed PWAs, in-app browsers).

```js
import vfUpdate from 'vfunc/plugins/update';     // <script>: dist/plugins/update.min.js → global vfUpdate
vf.use(vfUpdate, { url: './version.json', current: APP_VERSION, policy: 'next-navigation' });
```

| Policy | Behaviour |
|---|---|
| `next-navigation` (default) | replace on the next screen change; nothing in progress is lost |
| `prompt` | `onAvailable(info, apply)` lets the app show its own notice; replace when the user agrees |
| `immediate` | replace at once (security fixes) |

See [Deployment and cache](deploy.md) for the rest.

### Official plugin — `vf.ext.shortcut`

Keyboard shortcuts for the whole page. Keys typed into inputs are ignored unless you allow them, and so are keys that belong to an IME composition, so typing Korean, Japanese or Chinese never fires a shortcut.

```js
import vfShortcut from 'vfunc/plugins/shortcut';   // <script>: dist/plugins/shortcut.min.js → global vfShortcut
const keys = vf.use(vfShortcut);
const off = keys.add('mod+k', () => search.focus(), { label: 'Search' });   // mod = ⌘ on Apple devices, Ctrl elsewhere
keys.add('escape', closeDialog, { allowInInput: true });
keys.list();   // [{ combo: 'ctrl+k', label: 'Search' }, …] for your own help screen
off();         // remove one shortcut; keys.destroy() removes all
```

The newest shortcut of a combo wins, so a dialog can take `escape` while it is open and give it back with `off()`. The plugin draws no UI.

### Official plugin — `vf.ext.list`

A keyed list. A component's `render` redraws its whole inside, which is slow for long lists where a few rows change often (update, swap, remove). This plugin keeps one element per item, draws only the rows that changed and only moves rows when the order changes. The numbers are in the [FAQ](faq.md#how-slow-are-large-lists).

```js
import vfList from 'vfunc/plugins/list';   // <script>: dist/plugins/list.min.js → global vfList
const list = vf.use(vfList);
const rows = list.create('#tbody', {       // the direct parent of the rows (tbody, ul, div …); nothing else in it
  key: (item) => item.id,
  render: (item) => vf.html`<tr><td>${item.name}</td><td><button type="button" data-action="remove">Remove</button></td></tr>`
});
rows.set(items);                            // same key and same object: kept; a new object: only that row is drawn
rows.set(rows.items().filter((x) => x.id !== id));   // remove: only that row goes
```

- Make a new object when an item changes. If you changed one in place, call `rows.refresh(key)`.
- Each row carries `data-vf-key`; a delegated handler finds the item with `e.target.closest('[data-vf-key]')`.
- Inside a component, mark the container with `data-vf-keep` so the component's render leaves the rows alone, create the list in `onMount` and call `rows.destroy()` in `onDestroy`. A `vf.attach` target without render works too.
- `render` returns one element built with `vf.html`. A plain string is escaped as text and does not become a row.
- `vfunc-ui.js` (since 1.2.0) contains this plugin, so `vf.vfListView` already keeps its rows by key. Load `list.min.js` only for lists you build yourself.

### IE11 / Edge IE mode

One engine, several files. `vfunc.legacy.min.js` is transpiled to ES5 with a single Promise polyfill (about 10 KB gzip).

- **Your app code must be ES5 too**: no arrow functions, `const`/`let`, template literals or classes. Build markup with `vf.tpl('<b>{name}</b>', data)`.
- Use the `hash` router mode and plain CSS values (IE11 has no CSS variables).
- Polyfill anything else your app needs (`fetch`, `Object.assign`, …) yourself.
- Public sites use `<script type="module">` together with `<script nomodule>`. Open example 16 in Edge IE mode to check.

## Third-party integration

How to use existing libraries — maps, editors, charts, grids — in a vfunc app. There are four official adapters; for any other library, follow the steps below. From 1.0.0 the adapters ship in the `vfunc` package (`vfunc/adapters/*`).

### Integration levels

| Level | When | Result |
|---|---|---|
| L0 direct use | one screen | the vendor object created inside `vf.vfunc({ onMount, onUpdate, onDestroy })` |
| L1 app wrapper | several screens of one app | your app's `vfXxx(props)` factory with the props it needs |
| L2 contract adapter | swap engines by name, contribute it | `vf{Kind}{Vendor}` that keeps the kind's contract and passes the contract tests |

A Leaflet sample with the three levels side by side is in `layer2/examples/third-party-custom/`.

### Official adapters

They keep the same contracts as the built-in `vf.vfGrid` and `vf.vfChart`, so switching is a change of name. The vendor library is not bundled: the app loads it first (pass it as `lib` or use its global).

| Adapter | File | Vendor (checked version) | License | IE11 |
|---|---|---|---|---|
| `vf.vfGridAg` | `vfunc-grid-ag.js` | AG Grid Community 36.2.0 | MIT | no |
| `vf.vfGridTabulator` | `vfunc-grid-tabulator.js` | Tabulator 6.5.3 | MIT | no |
| `vf.vfChartChartjs` | `vfunc-chart-chartjs.js` | Chart.js 4.5.1 | MIT | no |
| `vf.vfChartEcharts` | `vfunc-chart-echarts.js` | Apache ECharts 6.1.0 | Apache-2.0 | no |

```html
<script src="https://cdn.jsdelivr.net/npm/echarts@6.1.0/dist/echarts.min.js"
        integrity="sha384-C2iskrW/uPW46KzOjrvJIQo4YkV8lkD+QS0CrDN18IIPIpT/g2USu8bTP3nvmIAD" crossorigin="anonymous"></script>
<script src="vfunc.min.js"></script>
<script src="vfunc-chart-echarts.min.js"></script>
```

- For IE11, use the built-in `vfGrid` and `vfChart`: the current versions of the four vendors do not support it.
- AG Grid Enterprise features need a separate commercial license from AG Grid; the adapter uses Community only.
- AG Grid 33 and later inject their own `<style>` elements and use `data:` images for the theme icons. Pick the page's CSP for your case. In every case `script-src` has no `'unsafe-inline'`.
  - **The server can make a nonce for every response (stays strict):** load `ag-grid-community.min.noStyle.js`, which injects no styles when it loads, and pass the same nonce as `options: { styleNonce: nonce }`. The CSP is `style-src 'self' 'nonce-…'; img-src 'self' data:`. Make a new nonce for every request; never a fixed value.
  - **A static page (no nonce):** `ag-grid-community.min.js` with `style-src 'self' 'unsafe-inline'; font-src 'self' data:; img-src 'self' data:`. This file also injects the legacy theme CSS and icon fonts when it loads.
  - **A static page whose `style-src` must stay strict too:** use `vf.vfGridTabulator` or the built-in `vf.vfGrid` instead of AG Grid.
- Chart.js cannot change the type of a chart in place, so `setType` creates a new chart; `.instance` is always the current one.
- Colors come from the `--vf-chart-1`–`8` tokens, so charts follow the dark theme.

### Steps

The numbers match the `TODO(n)` comments of the adapter template `layer2/adapters/_template/vfunc-kind-vendor.js`.

1. **License:** MIT, Apache-2.0, BSD and ISC can be used as they are. The GPL family affects how the app may ship. Revenue-based or commercial-only licenses are out. Add it to the app's NOTICE.
2. **Version and loading:** from a CDN, an exact version with `integrity` (SRI) and `crossorigin`. The library from the `lib` prop, else its global. Wait for asynchronous loading.
3. **Host element:** mark the element the vendor draws in with `data-vf-keep`. Never mix vendor DOM into `render` output.
4. **Create** in `onMount`, from props turned into vendor options.
5. **Update:** methods such as `setData` call the vendor's update API; do not create it again.
6. **Events:** vendor events go to props callbacks as `{ sender, event, data }`.
7. **Destroy** in `onDestroy`: the vendor's destroy, and every listener, observer, subscription and timer you added.
8. **Size:** `ResizeObserver` (else window resize) calls the vendor's resize.
9. **Theme:** read the `--vf-*` tokens and pass them as the vendor's colors and fonts; no color values in JS.
10. **Locale:** `vf.i18n.subscribe` changes the vendor's locale.
11. **XSS:** where the vendor takes HTML strings, give it `vf.esc` text or nodes built with `vf.html`.
12. **`.instance`:** expose the vendor object; say its features are outside the contract.
13. **Browsers:** state the vendor's support as it is.
14. **Check:** pass the contract tests, make a sample page, and create and destroy it 100 times to look for leaks.

### Common traps

- The vendor DOM disappears when a parent refreshes → use `data-vf-keep`
- Initialized twice when mounted again
- A document listener or a timer survives destroy
- Creating it before the library has loaded
- XSS through a vendor renderer or tooltip
- A strict CSP blocks a library that injects styles or fonts

### Contract tests

Give the `base`, `grid` and `chart` suites in `layer2/adapters/_contract/` a factory and functions that press the UI, and they check the contract. The base contract checks `.instance`, `refresh`, `destroy` (twice), `lib` injection, the callback shape, listeners and timers left after 100 create/destroy cycles, survival of a parent refresh, and no logged errors.

- node + happy-dom: a small mock of the vendor checks the adapter's wiring.
- Browser: `contract.html` runs the same suites with the real vendors from the CDN. The official adapters pass in Chromium, Firefox and WebKit.

### Bringing it in with AI

Give the prompt `layer2/ai/en/prompt-integrate-third-party.md` (Korean: `layer2/ai/ko/…`) the library name and exact version, its documentation link and the level you want: it writes the component or adapter, a sample page and the contract test setup by the steps above. Check the result with the contract tests.

### Sharing adapters and questions

To share an adapter or an app wrapper you made, or to ask where an integration got stuck, use the [Adapters category of Discussions](https://github.com/vidkid-indy/vfunc/discussions/categories/adapters). Publish yours as a separate package named `vfunc-adapter-*` and post it there, and we list it on this site. To propose an official adapter, discuss it there first and follow the steps in [CONTRIBUTING](https://github.com/vidkid-indy/vfunc/blob/main/CONTRIBUTING.md#adapters--어댑터-기여).

## Deployment and cache

### Files

| File | Use |
|---|---|
| `vfunc.js` / `vfunc.min.js` | `<script>` development / production (global `vf`) |
| `vfunc.esm.js` / `vfunc.esm.min.js` | ES module development / production |
| `vfunc.legacy.min.js` | IE11 / Edge IE mode |
| `plugins/update.min.js`, `plugins/update.esm.js` | the update plugin |
| `css/vfunc.tokens.css` | optional tokens |

Every file has a source map. Files are minified, never obfuscated.

### CDN: exact version + SRI

```html
<script src="https://cdn.jsdelivr.net/npm/vfunc@1.2.0/dist/vfunc.min.js"
        integrity="sha384-yTR0o8US3nk+D1XIBAsv1O/lMFA5tV3V021xPo8yxyqnBNSxi1rqINVvBOykAEkK" crossorigin="anonymous"></script>
```

`integrity` values differ per version and file; the ones above belong to the version this site was built from. Never load polyfills from a third-party CDN.

### Making every release arrive

Without a build there are no hashed file names, and `app.js?v=2` does not reach the modules it imports. Use four layers together:

1. **Cache headers**: `index.html` and `version.json` with `Cache-Control: no-cache`.
2. **Version folders**: copy each release into `/1.0.3/…` and point `index.html` at it. Every sub-module becomes the new version at once. The starter's `node tools/release.mjs 1.0.3` does it by copying only.
3. **The update plugin**: open pages switch to the new version on the next screen change.
4. **Pinned versions**: exact versions + SRI for every file from another domain.

| Path | Cache-Control |
|---|---|
| `/index.html`, `/version.json` | `no-cache` |
| `/<version>/…` | `public, max-age=31536000, immutable` |

Settings for Apache, Nginx, IIS, Tomcat, Netlify and GitHub Pages are in the starter's `deploy/` folder.

### Service Workers

The most common cause of "the update never arrives". Add one only if you need offline use: keep HTML network-first and prepare a way to unregister it.

### Security checklist

- Every page has a CSP meta tag without `'unsafe-inline'` in `script-src`; scripts and styles live in files.
- Permissions are checked on the server; no secrets in frontend code.
- User input and server data reach markup only through `vf.html`.

## API reference

The public API is exactly what `types/vfunc.d.ts` declares. Members starting with `_` are internal. Official `vf` members are read-only.

### Components

#### `vf.vfunc(options)`
Creates a component (`new` optional). Options:

| Option | Meaning |
|---|---|
| `tag` | root tag, default `'div'`; `'table'` when rendering table rows |
| `opts` | root element properties; `innerHTML` · `outerHTML` · `srcdoc` and string `on*` refused, URLs through `safeUrl` |
| `innerHTML` | fixed markup when there is no `render` (trusted as is) |
| `render(state)` | markup for the current state, written with `vf.html`; `this` is the instance |
| `replaceRoot` | `false` (default): 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` | state and methods; also reachable as `inst.key`, `inst.method()` |
| `events` | `[{ id?, eventType, onEvent? }]` direct listeners on the element with that `id` inside the root, or on the root when `id` is omitted |
| `delegates` | `[{ selector, eventType, onEvent? }]` delegated listeners |
| `childs` | child instances or nodes, `{ targetId, component }` slots |
| `onEvent`, `onError` | fallback handler, error report (the engine does not recover) |
| `onMount`, `onUpdate`, `onDestroy` | lifecycle; instances in `childs` also get `onMount` once, before their parent |

Instance: `$node`, `state`, `methods`, `ids`, `refs`, `setState(patch | (state) => patch)` (shallow merge, one render per tick), `scheduleRefresh()`, `refresh()`, `mount(parent)` → `Promise`, `destroy()`, `toString()`. `ids` and `refs` hold elements inside the root only (use `vf.$` outside it). `destroy()` destroys the instances in `childs` first. Reserved names (`state`, `refresh`, `mount` … and names starting with `_`) cannot be used as shortcut names for state keys, methods or ids. Do not add your own properties to an instance; keep listener functions and timers in a closure.

#### `vf.attach(target, options)`
Turns an element already in the page into a component. The options are those of `vf.vfunc`. The element is the root and keeps its attributes and listeners. Without `render` its markup and typed values stay as they are. With `render`, return **only the inside** of the element; it is parsed as content of the element's own tag, so rows can go straight into a `<tbody>`. Set state-dependent attributes of the root in `onMount`/`onUpdate`. `replaceRoot: true` replaces the element with the first element of the markup. Returns `null` when the target is missing. `destroy()` keeps the element in the page, releases the listeners and removes only what `render`/`innerHTML` drew, so the element can be attached again.

### Safe HTML

#### `vf.html`
Tagged template. Escapes each value for its position and refuses dangerous ones (`on*`, `<script>`, unquoted attributes). In a quoted attribute `null` and `undefined` become an empty value, arrays are joined with spaces, and `false` is empty too — except in `aria-*` and `data-*`, where booleans stay `"true"`/`"false"` (`aria-selected="${on}"`). Returns `SafeHtml`. In ES5 it can be called as a function: `vf.html(['<b>', '</b>'], value)`.

#### `vf.tpl(template, data)`
Fills `{key}` and `{user.name}` from own properties of `data`, without template literals. Same protection as `vf.html`.

#### `vf.unsafeHtml(markup)`
Marks markup as trusted. Only for markup you wrote, with a comment explaining why.

#### `vf.esc(value)`
A string with `& < > " '` escaped.

#### `vf.nl2br(value)`
Escapes and turns line breaks into `<br>`; returns `SafeHtml`.

#### `vf.safeUrl(url)`
Keeps relative URLs and `http` · `https` · `mailto` · `tel`; any other scheme becomes `'#'`.

#### `vf.SafeHtml`
The constructor of `vf.html` results (`value instanceof vf.SafeHtml`).

#### `vf.config(options)`
`{ strict, strictRender }`. With `strict: true` unsafe interpolation throws. `strictRender` warns (development build) when render returns a plain string.

### DOM and forms

#### `vf.$(selector, root?)`
`querySelector`.

#### `vf.$$(selector, root?)`
`querySelectorAll` as an array.

#### `vf.el(tag, props?)`
Creates an element and assigns properties with the same safety rules as `opts`.

#### `vf.node(markup)`
The first element of the markup, trusted as is. Parsed inside a `<div>`, so not for table rows.

#### `vf.frag(markup)`
A DocumentFragment with every top-level node.

#### `vf.idMap(root)`
`{ id: element }` for every descendant with an id.

#### `vf.form`
`vf.form.values(target, { skipPassword? })` returns `{ id: value }` (checkboxes as booleans, multiple selects as arrays); `vf.form.reset(target)` clears the controls and returns the values.

### SPA

#### `vf.router(options)`
`{ mode: 'hash' | 'history', base, routes, notFound, onChange, linkSelector, focus }` → `start()`, `stop()`, `go(path, { replace })`, `replace(path)`, `current()`, `href(path)`. Follows only app paths starting with `/`.

#### `vf.store(initial)`
`get(key?)` (the whole state without a key), `set(patch | (state) => patch)` (shallow merge: other keys stay; one notification per tick), `subscribe(fn)` (receives the new state) → an unsubscribe function.

### i18n

#### `vf.i18n`
`setup({ locale, fallback, locales, messages, load, persist })` → `Promise<locale>`, `set(locale)`, `locale()`, `add(locale, messages, { defaults }?)`, `subscribe(fn)`, `apply(root?)`. `set` loads the messages, then calls the subscribers, and resolves with the locale. `add(…, { defaults: true })` adds built-in component defaults: the app's messages win whatever the order, and the locale does not count as loaded, so `load` still runs.

#### `vf.t(key, params?)`
A message as plain text: `{name}` placeholders, plural forms chosen by `params.count`. `vf.t('nav.home')` finds `{ "nav": { "home": "…" } }` and `{ "nav.home": "…" }` alike.

#### `vf.fmt`
`number(n, opts)`, `currency(n, code, opts)`, `date(d, opts)`, `relative(n, unit)`, with `Intl` in the current locale, or plain strings without it.

### Extensions

#### `vf.use(plugin, options?)`
Installs `{ name, version?, requires?, install(vf, options) }` and stores what `install` returns in `vf.ext[name]`.

#### `vf.ext`
Installed extensions. User extensions live here only.

#### `vf.version`
The build version (for example `1.2.0`); `0.0.0-dev` when the source is imported directly.

### Official plugin

`vfunc/plugins/update` (`dist/plugins/update.min.js` → global `vfUpdate`): `vf.use(vfUpdate, { url, current, policy, interval, minGap, onAvailable, onError })` → `check(force)`, `status()`, `navigated()`, `apply()`, `stop()`. See [Extensions](extend.md#official-plugin-vfextupdate).

`vfunc/plugins/shortcut` (`dist/plugins/shortcut.min.js` → global `vfShortcut`): `vf.use(vfShortcut, { target, apple })` → `add(combo, handler, { label, allowInInput, preventDefault })` (returns a remover), `remove(combo, handler?)`, `list()`, `parse(combo)`, `destroy()`. See [Extensions](extend.md#official-plugin-vfextshortcut).

`vfunc/plugins/list` (`dist/plugins/list.min.js` → global `vfList`, since 1.1.0): `vf.use(vfList)` → `create(container, { key, render, items })` → `set(items)`, `refresh(key?)`, `items()`, `element(key)`, `destroy()`. `null` when the container is not found. See [Extensions](extend.md#official-plugin-vfextlist).

## Components

Layer 2 (`vfunc-ui`) is a set of components without classes, built on the engine. Use them where they save work and keep plain HTML everywhere else. From 1.0.0 it ships in the `vfunc` package.

### Loading

```html
<link rel="stylesheet" href="css/vfunc.tokens.css">
<link rel="stylesheet" href="css/vfunc-ui.css">

<script src="dist/vfunc.min.js"></script>
<script src="dist/vfunc-ui.min.js"></script>
<!-- when you need the grid and charts -->
<script src="dist/vfunc-ui-data.min.js"></script>
<!-- built-in Korean texts -->
<script src="dist/vfunc-ui.locale.ko.js"></script>
```

- With ES modules, `import 'vfunc/ui'` (and `import 'vfunc/ui/data'` for the grid and charts) after `import vf from 'vfunc'` adds the members to `vf`.
- IE11 uses `vfunc-ui.legacy.min.js`, `vfunc-ui-data.legacy.min.js` and `vfunc-ui.legacy.css`. `vfunc-all.legacy.min.js` holds the engine, the core and the data file in one file.

### How to use them

- `vf.vs*(props)` returns markup (SafeHtml). Put it in `vf.html` or `render` as is; it is not escaped twice.
- `vf.vf*(props)` returns an instance. Attach it with `.mount(el)` or put it in a parent component's `childs`. Callbacks receive `{ sender, event, data }`.
- Every `vs*` takes `id`, `ref` (`data-ref`), `action` (`data-action`), `className` and `describedBy`. Give a form control `label`, `hint` or `error` and it is wrapped in a linked field.
- Every string prop is escaped. Pass markup with `vf.html`.
- The slots of `vs*` (vsCard `body` and the like) take markup only. For a working component inside one, leave an empty element with an `id` and add `{ targetId, component }` to your component's `childs`. The content of vfTabs, vfAccordion, vfCarousel, vfPopover, vfModal and vfDrawer takes an instance as is and keeps it alive across re-renders.
- Delegate events on `data-action`; the `vf-*` classes are for design only.
- Built-in texts are message keys. Change them with props or `vf.i18n.add`.

```js
const save = vf.vfunc({
  render: () => vf.html`
    ${vf.vsInput({ name: 'email', type: 'email', label: 'Email', required: true })}
    ${vf.vsButton({ label: 'Save', variant: 'primary', action: 'save' })}`,
  delegates: [{ selector: '[data-action="save"]', eventType: 'click', onEvent: async () => {
    if (await confirmSave.open()) toast.show({ message: 'Saved', variant: 'success' });
  } }]
});
const confirmSave = vf.vfConfirm({ title: 'Save the changes?' });
const toast = vf.vfToast();
save.mount('#app');
```

### List

Tier is S (`vs*` only), P (`vs*` + `vf*`; the `vf*` renders with the `vs*`) or F (`vf*` only).

(See the website for the components list.)

### Gallery

Try every component on one page: the [component gallery](../layer2/examples/gallery/index.html). You can switch between English and Korean; the dark theme follows your OS.

### List for AI tools

The full list with props and methods is [ai/en/components.md](../ai/en/components.md). The build generates it from the catalog and the type declarations, so it always matches the code. Give it to your AI tool together with llms.txt.

### Other libraries

AG Grid, Tabulator, Chart.js and ECharts have official adapters. For a library that is not on the list, follow [Third-party integration](third-party.md).

## FAQ

### Can vfunc.js replace React or Vue?

For most business screens, behaviour on published pages, intranet systems and small SPAs it is enough. For screens that update thousands of rows often, large apps built by big teams, or when you need a rich ecosystem, React or Vue may fit better. See [Compare](compare.md).

### What are the limits?

- **Large lists**: a component's render replaces its whole inside (no keyed diff). For long lists where a few rows change often, draw only the changed rows with the official plugin [`vf.ext.list`](extend.md#official-plugin-vfextlist) (since 1.1.0). Keep unchanged areas with `data-vf-keep`. The built-in `vfGrid` pages long data instead of scrolling it; for virtual scrolling use a grid adapter (`vfGridAg`, `vfGridTabulator`). For numbers, see [the measurements below](#how-slow-are-large-lists).
- **Focus and caret**: after a render, focus and caret move back to the element with the same `id`, `data-ref` or `name`, else to the same `data-action` at the same position. Scroll positions are not restored. Do not render on every keystroke.
- **Table rows**: a component that renders `<tr>` needs `tag: 'table'`.
- **Ecosystem**: few component libraries and tools so far. Third-party libraries can be attached directly with `onMount` + `data-vf-keep`.

### How slow are large lists?

The operations of js-framework-benchmark, measured four ways. Naive: one component redraws the whole screen. Recommended: as the kit teaches, only the `<tbody>` is redrawn, and selecting a row changes an attribute without a render. vfList: the recommended page with the official list plugin, which draws and moves only the changed rows. Vanilla: hand-written code that touches only the changed rows. The numbers are the time from the click to the end of style and layout after the render; in parentheses, the ratio to vanilla.

(See the website for the bench list.)

- Creating rows and clearing them are close to vanilla in all four.
- Operations that change a few rows (partial update, swap, remove) redraw the whole list when drawn with render, several to tens of times slower: the cost of having no keyed diff. With vfList they stay within 1.5 times vanilla in all three engines.
- For operations that change only attributes (selection, expanding), change the attribute instead of drawing the row again (the recommended page): a new row element makes the browser lay out the whole table again.
- The numbers depend on the machine and the browser. How they are measured and how to run them yourself: `layer1/bench/README.md` in the repository. To compare with other frameworks, see the [js-framework-benchmark results](https://krausest.github.io/js-framework-benchmark/).

### What about server rendering and SEO?

vfunc assumes the HTML already exists. When a server (or static files) produces the HTML and vfunc only adds behaviour, search engines read that HTML. This site is built that way.

### How is security handled?

- `vf.html` escapes by position and refuses interpolation in dangerous places, `javascript:` URLs included.
- `opts` and `vf.el` refuse `innerHTML` and string handlers.
- `setState` and merges ignore dangerous keys such as `__proto__`.
- Permissions must be checked on the server; client code can always be bypassed.

If you find a security issue, follow `SECURITY.md` in the repository instead of opening a public issue.

### Can I use TypeScript?

Type declarations (`types/vfunc.d.ts`) ship with the package. Plain scripts without a build get editor type checking with `// @ts-check` and a reference to `types/global.d.ts`.

### Which browsers are supported?

| Build | Browsers |
|---|---|
| `vfunc.min.js`, ESM | Current Chrome, Edge, Firefox and Safari (desktop and mobile) |
| `vfunc.legacy.min.js` | Internet Explorer 11, Edge IE mode |

The examples, the starter and this site are tested automatically in Chromium, Firefox and WebKit on every change.

### Is IE11 supported?

`vfunc.legacy.min.js` runs in IE11 and Edge IE mode; your app code must be ES5 as well. See [Extensions, plugins, IE](extend.md#ie11-edge-ie-mode).

### What is the license?

Apache-2.0. The distributed files contain no third-party code; the tools and the libraries used by examples are all listed under [Licenses](licenses.md).

---

# Part 3 — Type declarations (the public API boundary)

## types/vfunc.d.ts

```ts
// SPDX-License-Identifier: Apache-2.0
//
// Type declarations of vfunc.js layer 1. This file is the boundary of the public API
// (CLAUDE.md rules 16 and 18, D-009): anything not declared here is internal, and names starting
// with "_" are never public. Written by hand; keep it in step with the API page of the website (site/content/*/api.md).

// ---------------------------------------------------------------------------------------------
// Safe HTML (manual section 4)
// ---------------------------------------------------------------------------------------------

/** Markup that vf.html trusts as-is. Created by vf.html, vf.tpl, vf.nl2br and vf.unsafeHtml. */
export interface SafeHtml {
  readonly value: string;
  toString(): string;
}

export interface SafeHtmlConstructor {
  new (value: string): SafeHtml;
  readonly prototype: SafeHtml;
}

/** For `instanceof` checks. Build markup with vf.html instead of calling this. */
export declare const SafeHtml: SafeHtmlConstructor;

/**
 * Tagged template that escapes each value for where it lands (text, quoted attribute, URL
 * attribute, bare attribute name, tag name). Event handler attributes, `srcdoc`, unquoted values
 * and `<script>`/`<style>` content are refused: the value is dropped and reported, or an error is
 * thrown with `vf.config({ strict: true })`.
 */
export declare function html(strings: TemplateStringsArray | readonly string[], ...values: unknown[]): SafeHtml;

/** vf.html for ES5 code: `{name}` and `{user.name}` are filled from own properties of `data`. */
export declare function tpl(template: string, data?: object): SafeHtml;

/** Trusted markup that vf.html will not escape. Never pass user data; comment why it is safe. */
export declare function unsafeHtml(markup: unknown): SafeHtml;

/** Escapes `& < > " '`. `null` and `undefined` become an empty string. */
export declare function esc(value: unknown): string;

/** Escapes and turns line breaks into `<br>`. */
export declare function nl2br(value: unknown): SafeHtml;

/** Relative URLs and http, https, mailto, tel pass unchanged; any other scheme gives `'#'`. */
export declare function safeUrl(url: unknown): string;

export interface VfConfig {
  /** Unsafe interpolation in vf.html throws instead of being dropped. */
  strict: boolean;
  /** Development build only: warn when render returns a plain string instead of vf.html output. */
  strictRender: boolean;
}

/** Reads or changes engine settings; returns a copy of the current settings. */
export declare function config(options?: Partial<VfConfig>): VfConfig;

// ---------------------------------------------------------------------------------------------
// Components (manual sections 2, 3 and 5)
// ---------------------------------------------------------------------------------------------

/** The event object passed to `onEvent` of events and delegates. */
export interface VfEvent<I = VfuncInstance> {
  /** The instance that received the event. */
  sender: I;
  /** The native event. */
  event: Event;
  /** `event.type`. */
  eventType: string;
  /** events: the element the listener is bound to. delegates: the element that matched the selector. */
  target: Element;
  /** events: the configured id (or the bound element's id). delegates: the matched element's id. */
  id: string;
  /** An empty object for your own use. */
  data: Record<string, unknown>;
}

/** Something that can be appended as a child: an instance or a DOM node. */
export type VfChild = { $node: Node } | Node;

export interface VfEventBinding<I> {
  /** The element with this id inside the root. Omitted: the root itself. */
  id?: string;
  eventType: string;
  onEvent?: (e: VfEvent<I>) => void;
}

export interface VfDelegateBinding<I> {
  /** Matched with `closest(selector)`; matches outside the root are ignored. */
  selector: string;
  eventType: string;
  onEvent?: (e: VfEvent<I>) => void;
}

export interface VfuncOptions<S extends object = Record<string, any>, M extends object = Record<string, any>> {
  /** Tag of the root element. Default `'div'`. */
  tag?: string;
  /** Properties assigned to the root element. innerHTML/outerHTML/srcdoc and string `on*` values are refused. */
  opts?: Record<string, unknown>;
  /** Initial markup when there is no render function. Trusted as-is: never put outside data here. */
  innerHTML?: string | SafeHtml;
  /** Returns the markup for the current state. Build it with vf.html. */
  render?: (this: VfuncInstance<S, M>, state: S) => SafeHtml | string;
  /** Use the first element of the markup as the root, instead of a `tag` wrapper (vf.vfunc) or the target element (vf.attach). */
  replaceRoot?: boolean;
  /** State. Each key is also readable and writable as `instance.key`. */
  state?: S;
  /** Methods bound to the instance, callable as `instance.name()`. */
  methods?: M & ThisType<VfuncInstance<S, M>>;
  events?: Array<VfEventBinding<VfuncInstance<S, M>>>;
  delegates?: Array<VfDelegateBinding<VfuncInstance<S, M>>>;
  /** Children appended after rendering; `{ targetId, component }` appends into that element. */
  childs?: Array<VfChild | { targetId: string; component: VfChild }>;
  /** Fallback handler for events and delegates without their own onEvent. */
  onEvent?: (e: VfEvent<VfuncInstance<S, M>>) => void;
  /** Called when render, a handler or a lifecycle hook throws. The engine does not recover. */
  onError?: (error: unknown) => void;
  /**
   * After mount() or vf.attach() put the element in the page. Instances in `childs` get it too,
   * once, before their parent. Create third-party widgets here.
   */
  onMount?: (instance: VfuncInstance<S, M>) => void;
  /** After every refresh. Without `render` nothing is drawn again, but it still runs after each state change. */
  onUpdate?: (instance: VfuncInstance<S, M>) => void;
  /**
   * In destroy(), after the instances in `childs` are destroyed, while the element is still in the
   * page. Release widgets and timers here.
   */
  onDestroy?: (instance: VfuncInstance<S, M>) => void;
}

/** Members every instance has. */
export interface VfuncBase<S extends object = Record<string, any>, M extends object = Record<string, any>> {
  /** The root element. */
  readonly $node: HTMLElement;
  /** The current state object. */
  state: S;
  /** The bound methods. */
  methods: M;
  /** Descendant elements with an id, inside the root only (use vf.$ for the rest of the page). Updated on every refresh. */
  ids: Record<string, HTMLElement>;
  /** Descendant elements with `data-ref`, inside the root only. Updated on every refresh. */
  refs: Record<string, HTMLElement>;
  readonly isvfunc: true;
  /**
   * Shallow merge and schedule one refresh per tick. Takes a patch or, like vf.store's set, a
   * function `(state) => patch`. `__proto__`, `constructor`, `prototype` are ignored.
   */
  setState(patch: (Partial<S> & Record<string, unknown>) | ((state: S) => Partial<S> & Record<string, unknown>)): void;
  /** Schedule one refresh after changing `instance.state` directly. */
  scheduleRefresh(): void;
  /** Render again now. */
  refresh(): void;
  /** Append to an element or selector and call onMount (instances in `childs` first). */
  mount(parent: Element | string): Promise<this>;
  /**
   * Destroy the instances in `childs`, call onDestroy, release listeners, remove the root, clear
   * ids and refs. Safe to call twice.
   * A vf.attach root stays in the page: only what render or innerHTML drew inside it is removed.
   */
  destroy(): void;
  /** The root's outerHTML, so an instance can be inserted with vf.html. */
  toString(): string;
}

/**
 * An instance. State keys, method names and element ids are also available directly on it
 * (priority: state > methods > ids), which the index signature stands for.
 */
export type VfuncInstance<S extends object = Record<string, any>, M extends object = Record<string, any>> =
  VfuncBase<S, M> & S & M & { [name: string]: any };

export interface VfuncConstructor {
  <S extends object = Record<string, any>, M extends object = Record<string, any>>(options?: VfuncOptions<S, M>): VfuncInstance<S, M>;
  new <S extends object = Record<string, any>, M extends object = Record<string, any>>(options?: VfuncOptions<S, M>): VfuncInstance<S, M>;
  readonly prototype: VfuncBase;
}

/** Creates a component. Callable with or without `new`. */
export declare const vfunc: VfuncConstructor;

/**
 * Turns an element that is already in the page into a component. The element itself is the root and
 * keeps its attributes; render/innerHTML fill only its inside (parsed as content of its own tag).
 * With `replaceRoot: true` the first element of the markup replaces the element. Returns null when the
 * target is not found.
 */
export declare function attach<S extends object = Record<string, any>, M extends object = Record<string, any>>(
  target: Element | string, options?: VfuncOptions<S, M>): VfuncInstance<S, M> | null;

// ---------------------------------------------------------------------------------------------
// DOM and form helpers (manual sections 6 and 7)
// ---------------------------------------------------------------------------------------------

/** `querySelector` on `root` (default: document). */
export declare function $(selector: string, root?: ParentNode): Element | null;

/** `querySelectorAll` on `root` (default: document), as an array. */
export declare function $$(selector: string, root?: ParentNode): Element[];

/** Creates an element and assigns properties with the same safety rules as `opts`. */
export declare function el<K extends keyof HTMLElementTagNameMap>(tag: K, props?: Record<string, unknown>): HTMLElementTagNameMap[K];
export declare function el(tag: string, props?: Record<string, unknown>): HTMLElement;

/** The first element of the markup, or null. The markup is trusted as-is. */
export declare function node(markup: string | SafeHtml): Element | null;

/** A DocumentFragment with every top-level node of the markup. The markup is trusted as-is. */
export declare function frag(markup: string | SafeHtml): DocumentFragment;

/** `{ id: element }` for every descendant with an id. Dangerous keys are skipped. */
export declare function idMap(root: ParentNode): Record<string, Element>;

export type FormTarget = Element | Document | DocumentFragment | Record<string, Element>;
export type FormValue = string | boolean | string[];

export interface VfForm {
  /** Reads `{ id: value }`. Checkboxes and radios give a boolean, a multiple select an array. */
  values(target: FormTarget, options?: { skipPassword?: boolean }): Record<string, FormValue>;
  /** Clears the controls (hidden inputs kept, selects back to `user-default`) and returns the values. */
  reset(target: FormTarget): Record<string, FormValue>;
}

export declare const form: VfForm;

// ---------------------------------------------------------------------------------------------
// SPA (manual section 8)
// ---------------------------------------------------------------------------------------------

export interface RouteContext {
  /** The path without query, e.g. "/users/7". */
  path: string;
  /** Values of ":name" segments, and `wildcard` for "*". */
  params: Record<string, string>;
  query: Record<string, string>;
  /** The matched pattern, or null when nothing matched. */
  route: string | null;
}

export interface RouterOptions {
  /** 'hash' (default: any static server, IE) or 'history' (the server must return index.html). */
  mode?: 'hash' | 'history';
  /** Leading path in history mode, e.g. '/app'. */
  base?: string;
  routes: Record<string, (ctx: RouteContext) => void>;
  notFound?: (ctx: RouteContext) => void;
  onChange?: (ctx: RouteContext) => void;
  /** Links handled by the router. Default 'a[data-link]'. */
  linkSelector?: string;
  /** Selector focused after each navigation (for screen readers). */
  focus?: string;
}

export interface Router {
  start(): void;
  stop(): void;
  /** Only app paths starting with "/" are followed; anything else is refused. */
  go(path: string, options?: { replace?: boolean }): void;
  replace(path: string): void;
  current(): RouteContext;
  /** The link address for a path: '#/x' (hash) or '/app/x' (history). */
  href(path: string): string;
}

/** Hash or history routing. Client-side routes are not access control; authorize on the server. */
export declare function router(options: RouterOptions): Router;

export interface Store<S extends object = Record<string, any>> {
  /** The state object (treat it as read-only). */
  get(): S;
  /** One key. */
  get<K extends keyof S>(key: K): S[K];
  /** Merges own, non-dangerous keys and notifies subscribers once per tick. */
  set(patch: Partial<S> | ((state: S) => Partial<S>)): void;
  /** Returns an unsubscribe function. */
  subscribe(listener: (state: S) => void): () => void;
}

/** A small shared state container. */
export declare function store<S extends object = Record<string, any>>(initial?: S): Store<S>;

// ---------------------------------------------------------------------------------------------
// Internationalization (manual section 9)
// ---------------------------------------------------------------------------------------------

/** A message: text with `{name}` placeholders, a plural object, or a nested group of messages. */
export type I18nMessage = string | { zero?: string; one?: string; other: string; [category: string]: string | undefined };
export interface I18nMessages { [key: string]: I18nMessage | I18nMessages }

export interface I18nSetupOptions {
  /** The locale to start with. Otherwise: persisted value, navigator.language, fallback. */
  locale?: string;
  /** Default 'en'. */
  fallback?: string;
  /** Allow-list of locales (recommended). */
  locales?: string[];
  messages?: Record<string, I18nMessages>;
  /** Loads the messages of a locale that has none yet, e.g. fetched JSON. */
  load?: (locale: string) => I18nMessages | Promise<I18nMessages>;
  /** Remember the choice in localStorage: true uses the key 'vf.locale', a string is the key. */
  persist?: boolean | string;
}

export interface VfI18n {
  /** Resolves with the chosen locale. */
  setup(options?: I18nSetupOptions): Promise<string>;
  /** Changes the locale, updates `<html lang>` and notifies subscribers. Resolves with the locale in use. */
  set(locale: string): Promise<string>;
  locale(): string;
  /**
   * Adds messages (deep merge; dangerous keys are ignored). With `{ defaults: true }` they are
   * built-in defaults (e.g. of layer 2 components): the app's messages win in any order, and the
   * locale does not count as loaded, so `load(locale)` still runs.
   */
  add(locale: string, messages: I18nMessages, options?: { defaults?: boolean }): void;
  /** Returns an unsubscribe function. */
  subscribe(listener: (locale: string) => void): () => void;
  /** Translates `data-i18n` (text only) and `data-i18n-attr` (allowed attributes only). */
  apply(root?: ParentNode): void;
}

export declare const i18n: VfI18n;

/** Translates a dotted key. Plain text: vf.html escapes it when inserted. `params.count` picks a plural. */
export declare function t(key: string, params?: Record<string, unknown>): string;

export interface VfFmt {
  number(value: number, options?: Intl.NumberFormatOptions): string;
  currency(value: number, currency: string, options?: Intl.NumberFormatOptions): string;
  date(value: Date | number | string, options?: Intl.DateTimeFormatOptions): string;
  /** e.g. relative(-3, 'day'). Plain text where Intl.RelativeTimeFormat is missing (IE11). */
  relative(value: number, unit: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year'): string;
}

/** Locale-aware formatting that follows vf.i18n.locale(). */
export declare const fmt: VfFmt;

// ---------------------------------------------------------------------------------------------
// Extensions (manual section 10)
// ---------------------------------------------------------------------------------------------

export interface VfPlugin<T = unknown, O = Record<string, unknown>> {
  /** Registered as vf.ext[name]. */
  name: string;
  version?: string;
  /** '*', 'x.y.z', '>=x.y.z' or '^x.y.z'. A mismatch warns; the plugin is still installed. */
  requires?: string;
  install(vf: Vf, options: O): T;
}

/** Installs an extension and returns what `install` returned (also stored in vf.ext[name]). */
export declare function use<T, O = Record<string, unknown>>(plugin: VfPlugin<T, O>, options?: O): T | undefined;

/** Installed extensions. User extensions live here, never on the vf root. */
export declare const ext: Record<string, any>;

/** The version of this build, e.g. "1.0.0". Importing the source directly gives "0.0.0-dev". */
export declare const version: string;

// ---------------------------------------------------------------------------------------------
// The vf object (default export and window.vf). Official members are read-only.
// ---------------------------------------------------------------------------------------------

export interface Vf {
  readonly vfunc: typeof vfunc;
  readonly attach: typeof attach;
  readonly html: typeof html;
  readonly unsafeHtml: typeof unsafeHtml;
  readonly tpl: typeof tpl;
  readonly esc: typeof esc;
  readonly nl2br: typeof nl2br;
  readonly safeUrl: typeof safeUrl;
  readonly $: typeof $;
  readonly $$: typeof $$;
  readonly el: typeof el;
  readonly node: typeof node;
  readonly frag: typeof frag;
  readonly idMap: typeof idMap;
  readonly form: typeof form;
  readonly router: typeof router;
  readonly store: typeof store;
  readonly i18n: typeof i18n;
  readonly t: typeof t;
  readonly fmt: typeof fmt;
  readonly use: typeof use;
  readonly ext: typeof ext;
  readonly config: typeof config;
  readonly SafeHtml: typeof SafeHtml;
  readonly version: typeof version;
}

declare const vf: Vf;
export default vf;
```

## types/global.d.ts

```ts
// SPDX-License-Identifier: Apache-2.0
//
// The global `vf` of the <script> builds (dist/vfunc.js, dist/vfunc.min.js).
// For type checking plain scripts, reference this file:
//   /// <reference path="./node_modules/vfunc/types/global.d.ts" />

import type { Vf } from './vfunc';

declare global {
  const vf: Vf;
  interface Window {
    vf: Vf;
  }
}

export {};
```

## types/plugins/update.d.ts

```ts
// SPDX-License-Identifier: Apache-2.0
//
// Types of the official update plugin (layer1/plugins/update.js, D-013).
//   import vfUpdate from 'vfunc/plugins/update';
//   const update = vf.use(vfUpdate, { url: './version.json', policy: 'next-navigation' });

import type { VfPlugin } from '../vfunc';

export type UpdatePolicy = 'next-navigation' | 'prompt' | 'immediate';

export interface UpdateInfo {
  current: string;
  latest: string;
  policy: UpdatePolicy;
}

export interface UpdateStatus extends UpdateInfo {
  /** A newer version was found and is waiting to be applied. */
  pending: boolean;
}

export interface UpdateOptions {
  /** Default './version.json'. The file is `{ "version": "1.0.3" }`, served with Cache-Control: no-cache. */
  url?: string;
  /** The running version. Empty: the first version read becomes the baseline. */
  current?: string;
  /** Default 'next-navigation'. 'prompt' needs onAvailable (otherwise it falls back to 'next-navigation'). */
  policy?: UpdatePolicy;
  /** Minutes between periodic checks. Default 10; 0 turns them off. */
  interval?: number;
  /** Seconds; checks closer together are skipped. Default 30. */
  minGap?: number;
  /** 'prompt' policy: show your own notice and call apply() to reload. */
  onAvailable?: (info: UpdateInfo, apply: () => void) => void;
  onError?: (error: unknown) => void;
  /** Replaces location.reload() (tests, custom handling). */
  reload?: () => void;
}

export interface UpdateApi {
  /** Reads version.json now; `force` ignores minGap. */
  check(force?: boolean): Promise<UpdateStatus>;
  /** Call from the router's onChange in history mode; hashchange and popstate are handled already. */
  navigated(): void;
  /** Reloads the page now. */
  apply(): void;
  status(): UpdateStatus;
  /** Removes the listeners and the timer. */
  stop(): void;
}

declare const vfUpdate: VfPlugin<UpdateApi, UpdateOptions>;
export default vfUpdate;
```

## types/plugins/shortcut.d.ts

```ts
// SPDX-License-Identifier: Apache-2.0
//
// Types of the official keyboard shortcut plugin (layer1/plugins/shortcut.js, D-030).
//   import vfShortcut from 'vfunc/plugins/shortcut';
//   const keys = vf.use(vfShortcut);
//   const off = keys.add('mod+k', () => openSearch(), { label: 'Search' });

import type { VfPlugin } from '../vfunc';

export interface ShortcutOptions {
  /** Where keydown is listened to. Default document. */
  target?: EventTarget;
  /** Treat `mod` as meta (true) or ctrl (false). Default: detected from the platform. */
  apple?: boolean;
}

export interface ShortcutAddOptions {
  /** Shown by list(), for a help screen. */
  label?: string;
  /** Also run while typing in inputs, textareas, selects and editable elements. Default false. */
  allowInInput?: boolean;
  /** Default true. */
  preventDefault?: boolean;
}

export interface ShortcutApi {
  /**
   * `combo`: modifiers ctrl, alt, shift, meta, mod (meta on Apple devices, ctrl elsewhere) and one
   * key as KeyboardEvent.key names it ('k', 'enter', 'escape', 'arrowup', 'f2', '?', 'space').
   * Keys of an IME composition never match. The newest shortcut of a combo wins.
   * Returns a function that removes the shortcut.
   */
  add(combo: string, handler: (event: KeyboardEvent, info: { combo: string; label: string }) => void, options?: ShortcutAddOptions): () => void;
  /** Removes the shortcuts of a combo, or only the one with this handler. */
  remove(combo: string, handler?: (...args: any[]) => void): void;
  /** One row per combo in canonical form ('ctrl+shift+k'), sorted. */
  list(): Array<{ combo: string; label: string }>;
  /** The canonical form of a combo, or '' when it is not valid. */
  parse(combo: string): string;
  /** Removes the listener and every shortcut. */
  destroy(): void;
}

declare const vfShortcut: VfPlugin<ShortcutApi, ShortcutOptions>;
export default vfShortcut;
```

## types/plugins/list.d.ts

```ts
// SPDX-License-Identifier: Apache-2.0
//
// Types of the official keyed list plugin (layer1/plugins/list.js, D-044).
//   import vfList from 'vfunc/plugins/list';
//   const list = vf.use(vfList);
//   const rows = list.create('#tbody', { key: (item) => item.id, render: (item) => vf.html`<tr>…</tr>` });
//   rows.set(items);

import type { SafeHtml, VfPlugin } from '../vfunc';

export interface ListOptions<T> {
  /** The item's key, unique in the list (string or number). Items without one are skipped. */
  key: (item: T) => string | number;
  /**
   * One element for the item, built with vf.html (a plain string is escaped as text, so it is not a row).
   * It is parsed inside the container's own tag, so a <tbody> container takes <tr> rows.
   */
  render: (item: T) => SafeHtml;
  /** Items to draw right away. */
  items?: T[];
}

export interface ListInstance<T> {
  /**
   * Shows the items in this order. An item whose key was shown before and is the same object keeps its
   * element; a new object for a key draws that row again; rows are moved to the new order; missing
   * keys are removed. Treat items as immutable, or call refresh(key) after changing one in place.
   */
  set(items: T[]): void;
  /** Draws one item again (its data changed in place), or every item without a key. */
  refresh(key?: string | number): void;
  /** The items shown, in order. */
  items(): T[];
  /** The row element of a key (it carries data-vf-key), or null. */
  element(key: string | number): Element | null;
  /** Removes the rows this list drew; later calls do nothing. */
  destroy(): void;
}

export interface ListApi {
  /**
   * A keyed list in `container`, the direct parent of the rows (tbody, ul, div …): an element, or a
   * selector for vf.$ ('#id', '[data-ref="x"]'). Put nothing else in it; inside a component mark it
   * with data-vf-keep. Returns null (and warns) when the container is not found.
   */
  create<T>(container: Element | string, options: ListOptions<T>): ListInstance<T> | null;
}

declare const vfList: VfPlugin<ListApi, Record<string, never>>;
export default vfList;
```

---

# Part 4 — Layer 2 components (ai/en/components.md)

Layer 2 of vfunc.js: components without classes on top of the engine (`vf.vfunc`). Use them where they save work; plain HTML is still fine.

- **Load:** `vfunc.js` → `vfunc-ui.js` (→ `vfunc-ui-data.js` for the grid and charts) (→ `vfunc-ui.locale.ko.js`), CSS `vfunc.tokens.css` + `vfunc-ui.css`. ES modules: `import 'vfunc/ui'` (and `'vfunc/ui/data'`) add the members to `vf`.
- **`vf.vs*` returns SafeHtml:** put it in `vf.html` templates or `render` as is (not escaped twice). It never holds state.
- **`vf.vf*` 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`.
- **Hooks:** `id`, `ref` (`data-ref`) and `action` (`data-action`) props; never select by the `vf-*` classes. Every string prop is escaped; pass `vf.html` for markup.
- **Text:** built-in messages are the keys listed per component; override them with props or `vf.i18n.add(locale, { key: text })`.
- Types below are the d.ts declarations without comments. Types used by several components come first.

### Shared types

```ts
interface VfUiEvent<D = Record<string, unknown>, I = VfuncInstance> {
  sender: I;
  event: Event | null;
  data: D;
}
type VfValueInstance<V, M = {}> = VfuncInstance & { getValue(): V; setValue(value: V): void; } & M;
type VsContent = string | number | SafeHtml;
interface VsCommonProps {
  id?: string;
  ref?: string;
  action?: string;
  describedBy?: string;
  className?: string;
}
interface VsFieldTextProps {
  label?: VsContent;
  hint?: VsContent;
  error?: VsContent;
  required?: boolean;
}
interface VsControlProps extends VsCommonProps, VsFieldTextProps {
  name?: string;
  disabled?: boolean;
  readonly?: boolean;
}
type VsOption = string | number | { value: string | number; label?: VsContent; disabled?: boolean };
type VsTone = 'neutral' | 'primary' | 'success' | 'warning' | 'danger' | 'info';
type VsSlot = VsContent | VsContent[];
type VfSlot = VsSlot | VfuncInstance;
interface VfMenuItem {
  label?: VsContent;
  action?: string;
  disabled?: boolean;
  danger?: boolean;
  separator?: boolean;
}
type VfPlacement = 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end';
interface VfModalMethods {
  open(): void;
  close(reason?: string): void;
  isOpen(): boolean;
}
interface VfToastOptions {
  message: VsContent;
  title?: VsContent;
  variant?: 'info' | 'success' | 'warning' | 'danger';
  duration?: number;
  action?: { label: string; onClick?: (e: VfUiEvent<{ id: string }>) => void };
}
interface VsTableColumn<T = any> {
  key: string;
  label: VsContent;
  align?: 'start' | 'center' | 'end';
  sortable?: boolean;
  render?: (row: T, index: number) => VsSlot;
}
interface VsFieldControlArgs {
  id: string;
  describedBy: string | null;
  invalid: boolean;
  required: boolean;
}
interface VfGridMethods<T = any> {
  setData(data: T[]): void;
  getData(): T[];
  setColumns(columns: Array<VsTableColumn<T>>): void;
  getSelection(): T[];
  clearSelection(): void;
  setPage(page: number): void;
  setQuery(query: string): void;
  setLoading(loading: boolean): void;
  setTotal(total: number): void;
  getValue(): string[];
  setValue(keys: string[]): void;
  readonly instance: unknown;
}
type VfChartType = 'bar' | 'line' | 'area' | 'pie' | 'donut' | 'sparkline';
interface VfChartData {
  labels: Array<string | number>;
  series: Array<{ name: string; data: number[] }>;
}
interface VfChartMethods {
  setData(data: VfChartData): void;
  setType(type: VfChartType): void;
  resize(): void;
  getValue(): VfChartData;
  setValue(data: VfChartData): void;
  readonly instance: unknown;
}
```

### Input

#### `vsField` — S

Label, hint and error around a control you build yourself; gives it the id and aria-describedby.

```js
vf.vsField({ label: 'Color', control: (a) => vf.html`<input type="color" id="${a.id}" aria-describedby="${a.describedBy}">` })
```

```ts
interface VsFieldProps extends VsFieldTextProps {
  id?: string;
  describedBy?: string;
  className?: string;
  control: (args: VsFieldControlArgs) => SafeHtml;
}
// Label, hint and error around a control you build yourself.
function vsField(props: VsFieldProps): SafeHtml;
```

#### `vsInput` — S

A text-like <input>; label, hint and error make it a linked field.

```js
vf.vsInput({ name: 'email', type: 'email', label: 'Email', error: errors.email })
```

```ts
interface VsInputProps extends VsControlProps {
  type?: 'text' | 'email' | 'tel' | 'url' | 'number' | 'search' | 'password' | 'date' | 'time' | 'datetime-local' | 'month' | 'week';
  value?: string | number;
  placeholder?: string;
  autocomplete?: string;
  inputmode?: string;
  pattern?: string;
  min?: string | number;
  max?: string | number;
  step?: string | number;
  minlength?: number;
  maxlength?: number;
  size?: 'md' | 'sm' | 'lg';
}
// An `<input class="vf-input">`, in a `.vf-field` when label, hint or error is given.
function vsInput(props: VsInputProps): SafeHtml;
```

#### `vsTextarea` — S

A <textarea> with the same field props as vsInput.

```js
vf.vsTextarea({ name: 'memo', label: 'Memo', rows: 4 })
```

```ts
interface VsTextareaProps extends VsControlProps {
  value?: string;
  rows?: number;
  placeholder?: string;
  minlength?: number;
  maxlength?: number;
  size?: 'md' | 'sm' | 'lg';
}
// A `<textarea class="vf-textarea">`.
function vsTextarea(props: VsTextareaProps): SafeHtml;
```

#### `vsSelect` — S

A native <select> from an options list, with groups, placeholder and multiple.

```js
vf.vsSelect({ name: 'role', label: 'Role', options: ['admin', 'user'], value: 'user' })
```

```ts
interface VsSelectProps extends VsControlProps {
  options: Array<VsOption | { label: string; options: VsOption[]; disabled?: boolean }>;
  value?: string | number | Array<string | number>;
  placeholder?: string;
  multiple?: boolean;
  size?: 'md' | 'sm' | 'lg';
}
// A `<select class="vf-select">`.
function vsSelect(props: VsSelectProps): SafeHtml;
```

#### `vsCheckbox` — S

A native checkbox with its label.

```js
vf.vsCheckbox({ name: 'agree', label: 'I agree', checked: true })
```

```ts
interface VsCheckboxProps extends VsControlProps {
  label: VsContent;
  checked?: boolean;
  value?: string;
}
// A native checkbox inside its `<label class="vf-check">`.
function vsCheckbox(props: VsCheckboxProps): SafeHtml;
```

#### `vsRadioGroup` — S

Radio buttons in a fieldset with a legend.

```js
vf.vsRadioGroup({ name: 'plan', label: 'Plan', options: ['free', 'pro'], value: 'free' })
```

```ts
interface VsRadioGroupProps extends VsControlProps {
  options: VsOption[];
  value?: string | number;
  direction?: 'vertical' | 'horizontal';
}
// Radio buttons in a `<fieldset class="vf-radio-group">`; `label` is the legend, `id` the fieldset's.
function vsRadioGroup(props: VsRadioGroupProps): SafeHtml;
```

#### `vsSwitch` — S

An on/off switch: a native checkbox with role="switch".

```js
vf.vsSwitch({ name: 'notify', label: 'Notifications', checked: true })
```

```ts
// An on/off switch: a native checkbox with `role="switch"`.
function vsSwitch(props: VsCheckboxProps): SafeHtml;
```

#### `vsSlider` — S

A native range slider.

```js
vf.vsSlider({ name: 'volume', label: 'Volume', value: 30 })
```

```ts
interface VsSliderProps extends VsControlProps {
  value?: number;
  min?: number;
  max?: number;
  step?: number;
}
// A native range `<input class="vf-slider">`.
function vsSlider(props: VsSliderProps): SafeHtml;
```

#### `vsProgress` — S

A native progress bar; no value shows the indeterminate state.

```js
vf.vsProgress({ label: 'Upload', value: 42, showValue: true })
```

```ts
interface VsProgressProps extends VsCommonProps {
  value?: number | null;
  max?: number;
  label?: VsContent;
  hint?: VsContent;
  showValue?: boolean;
}
// A native `<progress class="vf-progress">`.
function vsProgress(props: VsProgressProps): SafeHtml;
```

#### `vsNumberInput` · `vfNumberInput` — P

A number input with decrease/increase buttons; vf* steps, clamps to min/max and rounds to the step.

Messages: `numberInput.decrement`, `numberInput.increment`

```js
vf.vfNumberInput({ name: 'qty', label: 'Quantity', value: 1, min: 1, max: 99, onChange: (e) => setQty(e.data.value) })
```

```ts
interface VsNumberInputProps extends VsControlProps {
  value?: number | null;
  min?: number;
  max?: number;
  step?: number;
  placeholder?: string;
  size?: 'md' | 'sm' | 'lg';
  decrementLabel?: string;
  incrementLabel?: string;
}
// An `<input type="number">` between buttons with data-action "decrement" / "increment".
function vsNumberInput(props: VsNumberInputProps): SafeHtml;
interface VfNumberInputProps extends VsNumberInputProps {
  onChange?: (e: VfUiEvent<{ value: number | null }>) => void;
}
// Steps with the buttons, clamps and rounds on commit.
function vfNumberInput(props: VfNumberInputProps): VfValueInstance<number | null>;
```

#### `vsSearchInput` · `vfSearchInput` — P

A search box with a clear button; vf* debounces onSearch (IME-aware), searches at once on Enter.

Messages: `searchInput.clear`, `searchInput.label`, `searchInput.placeholder`

```js
vf.vfSearchInput({ debounce: 300, onSearch: (e) => load(e.data.value) })
```

```ts
interface VsSearchInputProps extends VsControlProps {
  value?: string;
  placeholder?: string;
  ariaLabel?: string;
  clearLabel?: string;
  size?: 'md' | 'sm' | 'lg';
}
// An `<input type="search">` with a clear button (data-action "clear").
function vsSearchInput(props: VsSearchInputProps): SafeHtml;
interface VfSearchInputProps extends VsSearchInputProps {
  debounce?: number;
  onSearch?: (e: VfUiEvent<{ value: string }>) => void;
  onClear?: (e: VfUiEvent<{}>) => void;
}
function vfSearchInput(props: VfSearchInputProps): VfValueInstance<string, { clear(): void; focus(): void }>;
```

#### `vsPasswordInput` · `vfPasswordInput` — P

A password input with a show/hide button (aria-pressed).

Messages: `passwordInput.hide`, `passwordInput.show`

```js
vf.vfPasswordInput({ name: 'password', label: 'Password', autocomplete: 'new-password' })
```

```ts
interface VsPasswordInputProps extends VsControlProps {
  value?: string;
  visible?: boolean;
  autocomplete?: string;
  placeholder?: string;
  minlength?: number;
  maxlength?: number;
  size?: 'md' | 'sm' | 'lg';
  showLabel?: string;
  hideLabel?: string;
}
// A password input with a toggle button (data-action "toggle-visibility", aria-pressed).
function vsPasswordInput(props: VsPasswordInputProps): SafeHtml;
interface VfPasswordInputProps extends VsPasswordInputProps {
  onChange?: (e: VfUiEvent<{ value: string }>) => void;
  onToggle?: (e: VfUiEvent<{ visible: boolean }>) => void;
}
function vfPasswordInput(props: VfPasswordInputProps): VfValueInstance<string, { toggle(visible?: boolean): void }>;
```

#### `vsChipsInput` · `vfChipsInput` — P

Chips (vsTag) and a text input; Enter or comma adds, Backspace removes; hidden inputs for forms.

```js
vf.vfChipsInput({ name: 'tags', label: 'Tags', value: ['ui'], max: 5, onChange: (e) => save(e.data.value) })
```

```ts
interface VsChipsInputProps extends VsControlProps {
  value?: string[];
  placeholder?: string;
  max?: number;
}
// vsTag chips (data-action "remove") and a text input; one hidden input per chip when `name` is set.
function vsChipsInput(props: VsChipsInputProps): SafeHtml;
interface VfChipsInputProps extends VsChipsInputProps {
  onChange?: (e: VfUiEvent<{ value: string[] }>) => void;
}
// Enter or comma adds, Backspace in the empty input removes the last chip.
function vfChipsInput(props: VfChipsInputProps): VfValueInstance<string[], { add(text: string): boolean; remove(text: string): void }>;
```

#### `vsRating` · `vfRating` — P

Stars on native radios (keyboard works); readonly shows an image with a text alternative.

Messages: `rating.label`, `rating.value`

```js
vf.vfRating({ name: 'score', value: 3, onChange: (e) => rate(e.data.value) })
```

```ts
interface VsRatingProps extends VsCommonProps {
  value?: number;
  max?: number;
  readonly?: boolean;
  label?: VsContent;
  name?: string;
  disabled?: boolean;
  required?: boolean;
  hint?: VsContent;
  error?: VsContent;
}
// Stars on radios (data-action "rate") in a fieldset; readonly: `role="img"` with "{value} of {max}".
function vsRating(props: VsRatingProps): SafeHtml;
interface VfRatingProps extends VsRatingProps {
  onChange?: (e: VfUiEvent<{ value: number }>) => void;
}
function vfRating(props: VfRatingProps): VfValueInstance<number>;
```

#### `vsSelectButton` · `vfSelectButton` — P

Options as aria-pressed toggle buttons; one choice or several with multiple.

```js
vf.vfSelectButton({ ariaLabel: 'Period', options: ['day', 'week', 'month'], value: 'week', onChange: (e) => setPeriod(e.data.value) })
```

```ts
interface VsSelectButtonProps extends VsCommonProps {
  options: VsOption[];
  value?: string | number | Array<string | number>;
  multiple?: boolean;
  label?: VsContent;
  ariaLabel?: string;
  name?: string;
  disabled?: boolean;
  hint?: VsContent;
  error?: VsContent;
  size?: 'md' | 'sm' | 'lg';
}
// Toggle buttons (data-action "select", data-value, aria-pressed) in a `role="group"`.
function vsSelectButton(props: VsSelectButtonProps): SafeHtml;
interface VfSelectButtonProps extends VsSelectButtonProps {
  onChange?: (e: VfUiEvent<{ value: string | string[] }>) => void;
}
function vfSelectButton(props: VfSelectButtonProps): VfValueInstance<string | number | Array<string | number>>;
```

#### `vsMaskedInput` · `vfMaskedInput` — P

A text input formatted by a mask (0 digit, a letter, * either); vf* keeps the caret and gives the raw value.

```js
vf.vfMaskedInput({ name: 'phone', label: 'Phone', mask: '000-0000-0000', onChange: (e) => save(e.data.raw) })
```

```ts
interface VsMaskedInputProps extends VsControlProps {
  mask: string;
  value?: string;
  placeholder?: string;
  autocomplete?: string;
  size?: 'md' | 'sm' | 'lg';
}
// A text `<input class="vf-input" data-mask>` with the value formatted by the mask.
function vsMaskedInput(props: VsMaskedInputProps): SafeHtml;
interface VfMaskedInputProps extends VsMaskedInputProps {
  onInput?: (e: VfUiEvent<{ value: string; raw: string }>) => void;
  onChange?: (e: VfUiEvent<{ value: string; raw: string }>) => void;
}
function vfMaskedInput(props: VfMaskedInputProps): VfValueInstance<string, { getRawValue(): string }>;
```

#### `vsDatePicker` · `vfDatePicker` — P

A native date input with 'YYYY-MM-DD' values; vf* normalizes typed text (IE11) and gives a Date.

Messages: `datePicker.placeholder`

```js
vf.vfDatePicker({ name: 'due', label: 'Due date', min: new Date(), onChange: (e) => setDue(e.data.date) })
```

```ts
interface VsDatePickerProps extends VsControlProps {
  value?: string | Date;
  min?: string | Date;
  max?: string | Date;
  placeholder?: string;
  size?: 'md' | 'sm' | 'lg';
}
// A native `<input type="date" class="vf-input">`.
function vsDatePicker(props: VsDatePickerProps): SafeHtml;
interface VfDatePickerProps extends VsDatePickerProps {
  onChange?: (e: VfUiEvent<{ value: string; date: Date | null }>) => void;
}
// Normalizes typed dates where the input is text; `aria-invalid` for text that is not a date.
function vfDatePicker(props: VfDatePickerProps): VfValueInstance<string, { getDate(): Date | null }>;
```

#### `vsTimePicker` · `vfTimePicker` — P

A native time input with 'HH:mm' values; vf* normalizes typed text (IE11).

Messages: `timePicker.placeholder`

```js
vf.vfTimePicker({ name: 'at', label: 'Time', step: 900 })
```

```ts
interface VsTimePickerProps extends VsControlProps {
  value?: string | Date;
  min?: string;
  max?: string;
  step?: number;
  placeholder?: string;
  size?: 'md' | 'sm' | 'lg';
}
// A native `<input type="time" class="vf-input">`.
function vsTimePicker(props: VsTimePickerProps): SafeHtml;
interface VfTimePickerProps extends VsTimePickerProps {
  onChange?: (e: VfUiEvent<{ value: string }>) => void;
}
function vfTimePicker(props: VfTimePickerProps): VfValueInstance<string>;
```

#### `vfDateRangePicker` — F

Start and end dates on two native inputs; the end never goes before the start.

Messages: `datePicker.placeholder`, `dateRangePicker.end`, `dateRangePicker.start`

```js
vf.vfDateRangePicker({ label: 'Period', names: ['from', 'to'], onChange: (e) => search(e.data.start, e.data.end) })
```

```ts
interface VfDateRangePickerProps extends VsCommonProps {
  start?: string | Date;
  end?: string | Date;
  min?: string | Date;
  max?: string | Date;
  names?: [string, string];
  label?: VsContent;
  startLabel?: string;
  endLabel?: string;
  disabled?: boolean;
  readonly?: boolean;
  required?: boolean;
  hint?: VsContent;
  error?: VsContent;
  onChange?: (e: VfUiEvent<{ start: string; end: string; startDate: Date | null; endDate: Date | null }>) => void;
}
// Two native date inputs (data-action "start" / "end") in a fieldset; the end never precedes the start.
function vfDateRangePicker(props: VfDateRangePickerProps): VfValueInstance<{ start: string; end: string }>;
```

### Display

#### `vsButton` — S

A button with variant, size, loading state and data-action / data-ref hooks.

Messages: `common.loading`

```js
vf.vsButton({ label: 'Save', variant: 'primary', action: 'save' })
```

```ts
interface VsButtonProps {
  label: string | SafeHtml;
  variant?: 'secondary' | 'primary' | 'danger' | 'ghost';
  size?: 'md' | 'sm' | 'lg';
  type?: 'button' | 'submit' | 'reset';
  action?: string;
  ref?: string;
  id?: string;
  disabled?: boolean;
  loading?: boolean;
  loadingText?: string;
  ariaLabel?: string;
  describedBy?: string;
  aria?: Record<string, string | number | boolean | null | undefined>;
  className?: string;
}
// A `<button class="vf-button">`.
function vsButton(props: VsButtonProps): SafeHtml;
```

#### `vsButtonGroup` — S

Buttons side by side in a role="group".

```js
vf.vsButtonGroup({ label: 'View', attached: true, buttons: [{ label: 'List', action: 'list' }, { label: 'Grid', action: 'grid' }] })
```

```ts
interface VsButtonGroupProps {
  buttons: VsButtonProps[];
  label?: string;
  size?: 'md' | 'sm' | 'lg';
  attached?: boolean;
  id?: string;
  ref?: string;
  className?: string;
}
// Buttons in a `<div role="group" class="vf-button-group">`.
function vsButtonGroup(props: VsButtonGroupProps): SafeHtml;
```

#### `vsBadge` — S

A small status label or count.

```js
vf.vsBadge({ label: 'Active', variant: 'success', dot: true })
```

```ts
interface VsBadgeProps extends VsCommonProps {
  label: VsContent;
  variant?: VsTone;
  dot?: boolean;
}
// A `<span class="vf-badge">`.
function vsBadge(props: VsBadgeProps): SafeHtml;
```

#### `vsTag` — S

A label, optionally with a remove button (data-action, data-value).

Messages: `tag.remove`

```js
vf.vsTag({ label: 'urgent', value: 'urgent', removable: true, removeAction: 'remove-tag' })
```

```ts
interface VsTagProps {
  label: VsContent;
  variant?: VsTone;
  value?: string;
  removable?: boolean;
  removeAction?: string;
  removeLabel?: string;
  disabled?: boolean;
  id?: string;
  ref?: string;
  className?: string;
}
// A `<span class="vf-tag">`; the app removes it in its own delegate.
function vsTag(props: VsTagProps): SafeHtml;
```

#### `vsAvatar` — S

A user picture, or the initials of the name.

```js
vf.vsAvatar({ name: 'Ada Lovelace', src: user.photo })
```

```ts
interface VsAvatarProps {
  name?: string;
  src?: string;
  alt?: string;
  size?: 'md' | 'sm' | 'lg';
  id?: string;
  ref?: string;
  className?: string;
}
// A `<span class="vf-avatar" role="img">` with an image or initials.
function vsAvatar(props: VsAvatarProps): SafeHtml;
```

#### `vsAlert` — S

A message box: info, success, warning, danger; optionally dismissible.

Messages: `alert.dismiss`

```js
vf.vsAlert({ variant: 'warning', title: 'Check', message: 'Unsaved changes', dismissible: true })
```

```ts
interface VsAlertProps {
  message?: VsContent;
  title?: VsContent;
  variant?: 'info' | 'success' | 'warning' | 'danger';
  dismissible?: boolean;
  dismissAction?: string;
  dismissLabel?: string;
  id?: string;
  ref?: string;
  className?: string;
}
// A `<div class="vf-alert">`.
function vsAlert(props: VsAlertProps): SafeHtml;
```

#### `vsCard` — S

A surface with header (title, subtitle, actions), body and footer.

```js
vf.vsCard({ title: 'Sales', body: vf.html`<p>${text}</p>`, footer: vf.vsButton({ label: 'More', action: 'more' }) })
```

```ts
interface VsCardProps {
  title?: VsContent;
  subtitle?: VsContent;
  actions?: VsSlot;
  body?: VsSlot;
  footer?: VsSlot;
  headingLevel?: 2 | 3 | 4 | 5 | 6;
  id?: string;
  ref?: string;
  className?: string;
}
// A `<div class="vf-card">`.
function vsCard(props: VsCardProps): SafeHtml;
```

#### `vsDescriptions` — S

Label/value pairs as a <dl>, in 1–4 columns.

```js
vf.vsDescriptions({ columns: 2, items: [{ label: 'Name', value: user.name }, { label: 'Email', value: user.email }] })
```

```ts
interface VsDescriptionsProps {
  items: Array<{ label: VsContent; value: VsSlot }>;
  columns?: 1 | 2 | 3 | 4;
  title?: VsContent;
  id?: string;
  ref?: string;
  className?: string;
}
// Label/value pairs as a `<dl>`.
function vsDescriptions(props: VsDescriptionsProps): SafeHtml;
```

#### `vsStatCard` — S

A key figure formatted with vf.fmt, with an optional change (+12.5%).

Messages: `statCard.down`, `statCard.up`

```js
vf.vsStatCard({ label: 'Revenue', value: 1250000, format: { style: 'currency', currency: 'KRW' }, delta: 0.125, deltaLabel: 'vs last month' })
```

```ts
interface VsStatCardProps {
  label: VsContent;
  value: VsContent;
  format?: Intl.NumberFormatOptions;
  delta?: number;
  deltaLabel?: VsContent;
  description?: VsContent;
  icon?: VsSlot;
  id?: string;
  ref?: string;
  className?: string;
}
// A key figure in a `<div class="vf-stat-card">`.
function vsStatCard(props: VsStatCardProps): SafeHtml;
```

#### `vsTimeline` — S

Events in order, with times formatted by vf.fmt.date.

```js
vf.vsTimeline({ items: [{ title: 'Order placed', time: order.createdAt, variant: 'success' }] })
```

```ts
interface VsTimelineProps {
  items: Array<{ title: VsContent; time?: Date | number | string; description?: VsContent; variant?: VsTone }>;
  timeFormat?: Intl.DateTimeFormatOptions;
  id?: string;
  ref?: string;
  className?: string;
}
// Events in an `<ol class="vf-timeline">`.
function vsTimeline(props: VsTimelineProps): SafeHtml;
```

#### `vsEmptyState` — S

What to show when a list or search has nothing.

Messages: `emptyState.title`

```js
vf.vsEmptyState({ description: 'Try another keyword', action: vf.vsButton({ label: 'Reset', action: 'reset' }) })
```

```ts
interface VsEmptyStateProps {
  title?: VsContent;
  description?: VsContent;
  icon?: VsSlot;
  action?: VsSlot;
  id?: string;
  ref?: string;
  className?: string;
}
// A `<div class="vf-empty-state">`.
function vsEmptyState(props: VsEmptyStateProps): SafeHtml;
```

#### `vsSkeleton` — S

Loading placeholders (text lines, rectangle, circle), hidden from screen readers.

```js
vf.vsSkeleton({ lines: 3 })
```

```ts
interface VsSkeletonProps {
  variant?: 'text' | 'rect' | 'circle';
  lines?: number;
  id?: string;
  ref?: string;
  className?: string;
}
// Placeholders, `aria-hidden`; mark the loading region with aria-busy.
function vsSkeleton(props: VsSkeletonProps): SafeHtml;
```

#### `vsSpinner` — S

A loading indicator with a hidden status text.

Messages: `common.loading`

```js
vf.vsSpinner({ size: 'sm' })
```

```ts
interface VsSpinnerProps {
  label?: string;
  size?: 'md' | 'sm' | 'lg';
  id?: string;
  ref?: string;
  className?: string;
}
// A `<span class="vf-spinner" role="status">`.
function vsSpinner(props: VsSpinnerProps): SafeHtml;
```

#### `vsTooltip` — S

A short text on hover and focus, linked with aria-describedby; CSS only.

```js
vf.vsTooltip({ text: 'Copy link', trigger: (a) => vf.vsButton({ label: 'Copy', action: 'copy', describedBy: a.describedBy }) })
```

```ts
interface VsTooltipProps {
  text: string;
  trigger: ((args: { describedBy: string }) => SafeHtml) | SafeHtml;
  placement?: 'top' | 'bottom' | 'start' | 'end';
  id?: string;
  ref?: string;
  className?: string;
}
// A trigger with a CSS-only tooltip (hover and focus).
function vsTooltip(props: VsTooltipProps): SafeHtml;
```

#### `vsListView` · `vfListView` — P

A list of items; with selectable, a listbox with roving focus (arrows, Space, Enter).

```js
vf.vfListView({ label: 'Users', items: users, selectable: 'single', onSelect: (e) => open(e.data.value) })
```

```ts
interface VsListViewProps<T = any> {
  items: T[];
  render?: (item: T, index: number) => SafeHtml;
  itemKey?: string;
  selectable?: 'none' | 'single' | 'multiple';
  selected?: string | string[];
  label?: string;
  emptyText?: VsContent;
  id?: string;
  ref?: string;
  className?: string;
}
// A `<ul class="vf-list-view">`, or an empty state when there are no items.
function vsListView<T = any>(props: VsListViewProps<T>): SafeHtml;
interface VfListViewProps<T = any> extends VsListViewProps<T> {
  onSelect?: (e: VfUiEvent<{ value: string | string[]; items: T[] }>) => void;
}
// Click, Space or Enter selects; Up, Down, Home, End move the focus. Since 1.2.0 the rows are kept by key (itemKey, else the position): setItems draws only new or changed items (give a changed item a new object), and selecting changes aria-selected and tabindex without drawing the list again. Its options have no id or data-index; find one by data-value. A render that takes the index draws a row again when its position changes.
function vfListView<T = any>(props: VfListViewProps<T>): VfValueInstance<string | string[] | null, { setItems(items: T[]): void }>;
```

#### `vfCarousel` — F

Slides one at a time with previous/next, dots and optional autoplay that pauses on hover, focus and reduced motion.

Messages: `carousel.carousel`, `carousel.goTo`, `carousel.next`, `carousel.pause`, `carousel.play`, `carousel.position`, `carousel.prev`, `carousel.slide`

```js
vf.vfCarousel({ label: 'News', items: [{ src: '/a.jpg', alt: 'Launch' }, { content: vf.html`<p>${text}</p>` }], autoplay: 5000 })
```

```ts
interface VfCarouselProps {
  items: Array<{ content?: VfSlot; src?: string; alt?: string }>;
  label: string;
  index?: number;
  loop?: boolean;
  autoplay?: number;
  showDots?: boolean;
  onChange?: (e: VfUiEvent<{ index: number }>) => void;
  id?: string;
  ref?: string;
  className?: string;
}
// A `<section aria-roledescription="carousel">` (WAI-ARIA carousel pattern).
function vfCarousel(props: VfCarouselProps): VfValueInstance<number, { next(): void; prev(): void; goTo(index: number): void; play(): void; pause(): void; }>;
```

### Navigation

#### `vsBreadcrumb` — S

The path to the current page; the last item has aria-current="page".

Messages: `breadcrumb.label`

```js
vf.vsBreadcrumb({ items: [{ label: 'Home', href: '#/' }, { label: 'Users', href: '#/users' }, { label: user.name }] })
```

```ts
interface VsBreadcrumbProps {
  items: Array<{ label: VsContent; href?: string }>;
  label?: string;
  id?: string;
  ref?: string;
  className?: string;
}
// A `<nav class="vf-breadcrumb">` with an ordered list.
function vsBreadcrumb(props: VsBreadcrumbProps): SafeHtml;
```

#### `vsPagination` · `vfPagination` — P

Page buttons with previous/next and gaps; vf* changes the page and calls onChange.

Messages: `pagination.label`, `pagination.next`, `pagination.page`, `pagination.previous`

```js
vf.vfPagination({ total: 230, pageSize: 20, onChange: (e) => load(e.data.page) })
```

```ts
interface VsPaginationProps {
  total: number;
  page?: number;
  pageSize?: number;
  siblings?: number;
  label?: string;
  id?: string;
  ref?: string;
  className?: string;
}
// Page buttons (data-action "page", data-page) in a `<nav class="vf-pagination">`.
function vsPagination(props: VsPaginationProps): SafeHtml;
interface VfPaginationProps extends VsPaginationProps {
  onChange?: (e: VfUiEvent<{ page: number }>) => void;
}
function vfPagination(props: VfPaginationProps): VfValueInstance<number, { setTotal(total: number): void }>;
```

#### `vsTabs` · `vfTabs` — P

Tabs and panels (WAI-ARIA): roving tabindex; vf* adds arrow keys (RTL aware), Home and End.

```js
vf.vfTabs({ label: 'Settings', tabs: [{ id: 'profile', label: 'Profile', content: profileHtml }, { id: 'security', label: 'Security', content: securityHtml }] })
```

```ts
interface VsTabsProps {
  tabs: Array<{ id: string; label: VsContent; content?: VsSlot; disabled?: boolean }>;
  active?: string;
  label?: string;
  id?: string;
  ref?: string;
  className?: string;
}
// Tabs (data-action "tab") and their panels; inactive panels are hidden.
function vsTabs(props: VsTabsProps): SafeHtml;
interface VfTabsProps extends Omit<VsTabsProps, 'tabs'> {
  tabs: Array<{ id: string; label: VsContent; content?: VfSlot; disabled?: boolean }>;
  onChange?: (e: VfUiEvent<{ id: string; index: number }>) => void;
}
// Click, arrow keys (following dir="rtl"), Home and End.
function vfTabs(props: VfTabsProps): VfValueInstance<string | null, { select(id: string): void }>;
```

#### `vsAccordion` · `vfAccordion` — P

Sections with heading buttons (aria-expanded) and region panels; one or multiple open.

```js
vf.vfAccordion({ items: faq.map((q) => ({ id: q.id, title: q.question, content: q.answer })) })
```

```ts
interface VsAccordionProps {
  items: Array<{ id: string; title: VsContent; content?: VsSlot; open?: boolean; disabled?: boolean }>;
  open?: string[];
  headingLevel?: 2 | 3 | 4 | 5 | 6;
  id?: string;
  ref?: string;
  className?: string;
}
// Heading buttons (data-action "toggle", aria-expanded) with region panels.
function vsAccordion(props: VsAccordionProps): SafeHtml;
interface VfAccordionProps extends Omit<VsAccordionProps, 'items'> {
  items: Array<{ id: string; title: VsContent; content?: VfSlot; open?: boolean; disabled?: boolean }>;
  multiple?: boolean;
  onToggle?: (e: VfUiEvent<{ id: string; open: boolean; openIds: string[] }>) => void;
}
function vfAccordion(props: VfAccordionProps): VfValueInstance<string[], { open(id: string): void; close(id: string): void; toggle(id: string): void; }>;
```

#### `vsStepper` · `vfStepper` — P

The steps of a process: complete, current (aria-current="step"), upcoming.

Messages: `stepper.complete`

```js
vf.vfStepper({ steps: ['Cart', 'Shipping', 'Payment'], active: 1 })
```

```ts
interface VsStepperProps {
  steps: Array<VsContent | { label: VsContent; description?: VsContent }>;
  active?: number;
  clickable?: boolean;
  label?: string;
  id?: string;
  ref?: string;
  className?: string;
}
// An `<ol class="vf-stepper">`: data-state complete / current / upcoming, aria-current="step".
function vsStepper(props: VsStepperProps): SafeHtml;
interface VfStepperProps extends VsStepperProps {
  onChange?: (e: VfUiEvent<{ index: number }>) => void;
}
function vfStepper(props: VfStepperProps): VfValueInstance<number, { next(): void; prev(): void; goTo(index: number): void; }>;
```

#### `vsSplitButton` · `vfSplitButton` — P

A main action with a menu of related actions (the vfDropdown menu).

Messages: `splitButton.more`

```js
vf.vfSplitButton({ label: 'Save', variant: 'primary', items: [{ label: 'Save as draft', action: 'draft' }], onClick: save, onSelect: (e) => run(e.data.action) })
```

```ts
interface VsSplitButtonProps {
  label: string | SafeHtml;
  action?: string;
  items: VfMenuItem[];
  variant?: 'secondary' | 'primary' | 'danger' | 'ghost';
  size?: 'md' | 'sm' | 'lg';
  disabled?: boolean;
  menuLabel?: string;
  id?: string;
  ref?: string;
  className?: string;
}
// A main button and a menu button (data-action "menu") in a `role="group"`, with a hidden menu.
function vsSplitButton(props: VsSplitButtonProps): SafeHtml;
interface VfSplitButtonProps extends VsSplitButtonProps {
  placement?: VfPlacement;
  onClick?: (e: VfUiEvent<{ action: string | undefined }>) => void;
  onSelect?: (e: VfUiEvent<{ action: string | undefined; item: VfMenuItem }>) => void;
}
function vfSplitButton(props: VfSplitButtonProps): VfuncInstance & { open(): void; close(): void; isOpen(): boolean };
```

### Overlay

#### `vfModal` — F

A modal dialog: focus kept inside and returned, Escape for the top layer, page scroll locked; footer actions through onAction.

Messages: `modal.close`

```js
const dialog = vf.vfModal({ title: 'Edit user', content: form, footer: vf.vsButton({ label: 'Save', action: 'save', variant: 'primary' }), onAction: (e) => save() }); dialog.open();
```

```ts
interface VfModalProps {
  title?: VsContent;
  label?: string;
  content?: VfSlot;
  footer?: VsSlot;
  size?: 'md' | 'sm' | 'lg';
  dismissible?: boolean;
  initialFocus?: string;
  closeLabel?: string;
  onOpen?: (e: VfUiEvent<{}>) => void;
  onClose?: (e: VfUiEvent<{ reason: string }>) => void;
  onAction?: (e: VfUiEvent<{ action: string }>) => void;
  id?: string;
  ref?: string;
  className?: string;
}
// A `role="dialog"` with `aria-modal` (no native <dialog>, same path in IE11).
function vfModal(props: VfModalProps): VfuncInstance & VfModalMethods;
```

#### `vfDrawer` — F

vfModal as a full-height panel at the end, start or bottom of the screen.

Messages: `modal.close`

```js
vf.vfDrawer({ title: 'Filters', side: 'end', content: filtersHtml }).open()
```

```ts
interface VfDrawerProps extends VfModalProps {
  side?: 'end' | 'start' | 'bottom';
}
// vfModal as a panel at one side of the screen.
function vfDrawer(props: VfDrawerProps): VfuncInstance & VfModalMethods;
```

#### `vfConfirm` — F

A yes/no alertdialog; open() returns a Promise of the answer; danger starts on cancel.

Messages: `confirm.cancel`, `confirm.ok`

```js
const c = vf.vfConfirm({ title: 'Delete 3 items?', variant: 'danger', confirmLabel: 'Delete' }); const ok = await c.open(); c.destroy(); if (ok) remove();
```

```ts
interface VfConfirmProps {
  title: VsContent;
  message?: VsContent;
  confirmLabel?: string;
  cancelLabel?: string;
  variant?: 'primary' | 'danger';
  id?: string;
  className?: string;
}
// A `role="alertdialog"`; Escape, the backdrop and the close button answer false.
function vfConfirm(props: VfConfirmProps): VfuncInstance & { open(): Promise<boolean>; close(reason?: string): void; isOpen(): boolean; };
```

#### `vfToast` — F

One notification region (live region); show() adds toasts that go after a while and stay while hovered or focused.

Messages: `toast.dismiss`, `toast.region`

```js
const toast = vf.vfToast(); toast.show({ message: 'Saved', variant: 'success' });
```

```ts
interface VfToastProps {
  position?: 'bottom-end' | 'bottom-start' | 'bottom-center' | 'top-end' | 'top-start' | 'top-center';
  duration?: number;
  max?: number;
  label?: string;
}
// The notification region (a live region added to document.body at once). Create it once.
function vfToast(props?: VfToastProps): VfuncInstance & { show(options: VfToastOptions): string; dismiss(id: string): void; clear(): void; };
```

#### `vfDropdown` — F

A button that opens a menu of actions (WAI-ARIA menu button: arrows, Home, End, letters, Escape).

```js
vf.vfDropdown({ trigger: { label: 'Actions' }, items: [{ label: 'Rename', action: 'rename' }, { separator: true }, { label: 'Delete', action: 'delete', danger: true }], onSelect: (e) => run(e.data.action) })
```

```ts
interface VfDropdownProps {
  trigger: Omit<VsButtonProps, 'id' | 'action' | 'aria'>;
  items: VfMenuItem[];
  placement?: VfPlacement;
  label?: string;
  onSelect?: (e: VfUiEvent<{ action: string | undefined; item: VfMenuItem }>) => void;
  id?: string;
  ref?: string;
  className?: string;
}
// A menu button (WAI-ARIA): arrows, Home, End, first letters, Escape, Tab.
function vfDropdown(props: VfDropdownProps): VfuncInstance & { open(): void; close(): void; isOpen(): boolean };
```

#### `vfPopover` — F

A non-modal dialog next to a button; Escape, an outside press or leaving it closes.

Messages: `modal.close`

```js
vf.vfPopover({ trigger: { label: 'Help' }, title: 'Shortcuts', content: vf.html`<p>Press / to search.</p>` })
```

```ts
interface VfPopoverProps {
  trigger: Omit<VsButtonProps, 'id' | 'action' | 'aria'>;
  content: VfSlot;
  title?: VsContent;
  label?: string;
  placement?: VfPlacement;
  onOpen?: (e: VfUiEvent<{}>) => void;
  onClose?: (e: VfUiEvent<{ reason: string }>) => void;
  id?: string;
  ref?: string;
  className?: string;
}
// A non-modal `role="dialog"` next to its trigger.
function vfPopover(props: VfPopoverProps): VfuncInstance & { open(): void; close(): void; isOpen(): boolean };
```

### Data

#### `vsTable` — S

A table with sortable header buttons (aria-sort, data-action="sort"), row keys, empty and loading states; with vfPagination and app state it makes list screens.

Messages: `common.loading`

```js
vf.vsTable({ caption: 'Users', columns: [{ key: 'name', label: 'Name', sortable: true }, { key: 'age', label: 'Age', align: 'end' }], data: rows, sort: state.sort })
```

```ts
interface VsTableProps<T = any> {
  columns: Array<VsTableColumn<T>>;
  data: T[];
  sort?: { key: string; dir: 'asc' | 'desc' } | null;
  rowKey?: string;
  selected?: string[];
  rowAction?: string;
  caption?: VsContent;
  emptyText?: VsContent;
  loading?: boolean;
  indexBase?: number;
  id?: string;
  ref?: string;
  className?: string;
}
// A `<table>` in a `<div class="vf-table">` (horizontal scroll).
function vsTable<T = any>(props: VsTableProps<T>): SafeHtml;
```

#### `vsSparkline` — S

A small static SVG trend (line or bars) with a text alternative; for tables and stat cards.

Messages: `sparkline.empty`, `sparkline.summary`

```js
vf.vsSparkline({ data: [3, 5, 4, 8, 7], type: 'line' })
```

```ts
interface VsSparklineProps {
  data: number[];
  type?: 'line' | 'bar';
  label?: string;
  format?: Intl.NumberFormatOptions;
  id?: string;
  ref?: string;
  className?: string;
}
// A small `<svg role="img" class="vf-sparkline">`; color is currentColor, size from CSS.
function vsSparkline(props: VsSparklineProps): SafeHtml;
```

#### `vfGrid` — F

A data grid (data file): sorting, paging, filter, row selection, server mode, fixed header; the G-1 grid contract.

File: `vfunc-ui-data.js` (load after `vfunc-ui.js`). Messages: `grid.range`, `grid.select`, `grid.selectAll`, `grid.selectRow`

```js
vf.vfGrid({ columns, data: users, pageSize: 20, selectable: 'multiple', onSelect: (e) => setSelected(e.data.keys) })
```

```ts
interface VfGridProps<T = any> {
  columns: Array<VsTableColumn<T>>;
  data: T[];
  pageSize?: number;
  selectable?: 'none' | 'single' | 'multiple' | boolean;
  height?: number | string;
  rowKey?: string;
  mode?: 'client' | 'server';
  total?: number;
  query?: string;
  sort?: { key: string; dir: 'asc' | 'desc' } | null;
  loading?: boolean;
  caption?: VsContent;
  emptyText?: VsContent;
  onRowClick?: (e: VfUiEvent<{ row: T | null; key: string; index: number }>) => void;
  onSelect?: (e: VfUiEvent<{ keys: string[]; rows: T[] }>) => void;
  onSort?: (e: VfUiEvent<{ key: string; dir: 'asc' | 'desc' }>) => void;
  onPage?: (e: VfUiEvent<{ page: number }>) => void;
  options?: unknown;
  lib?: unknown;
  id?: string;
  ref?: string;
  className?: string;
}
// A data grid on vsTable and vsPagination.
function vfGrid<T = any>(props: VfGridProps<T>): VfuncInstance & VfGridMethods<T>;
```

#### `vsChart` · `vfChart` — P

SVG charts (data file): bar, line, area, pie, donut, sparkline; colors from --vf-chart-* tokens. vfChart adds tooltips, legend toggles and redraws at its width.

File: `vfunc-ui-data.js` (load after `vfunc-ui.js`). Messages: `chart.label`, `chart.legend`, `chart.point`

```js
vf.vfChart({ type: 'line', label: 'Monthly sales', data: { labels: ['Jan', 'Feb', 'Mar'], series: [{ name: '2026', data: [12, 19, 15] }] } })
```

```ts
interface VsChartProps {
  type?: VfChartType;
  data: VfChartData;
  label?: string;
  height?: number;
  width?: number;
  valueFormat?: Intl.NumberFormatOptions;
  legend?: boolean;
  dataTable?: boolean;
  id?: string;
  ref?: string;
  className?: string;
}
// A `<figure class="vf-chart">` with an `<svg role="img">`.
function vsChart(props: VsChartProps): SafeHtml;
interface VfChartProps extends VsChartProps {
  onClick?: (e: VfUiEvent<{ series: string | null; index: number; label: string | number; value: number | null }>) => void;
  options?: unknown;
  lib?: unknown;
}
// vsChart with focusable marks and a tooltip, legend toggles, a fade-in on new data, width tracking.
function vfChart(props: VfChartProps): VfuncInstance & VfChartMethods;
```

### Adapters (same props and methods as the built-in grid / chart, plus `lib` and `options`)

#### `vfChartChartjs`

File: `vfunc-chart-chartjs.js`

```ts
interface VfChartChartjsProps extends VfChartProps {
  lib?: unknown;
  options?: Record<string, unknown>;
}
function vfChartChartjs(props: VfChartChartjsProps): VfuncInstance & VfChartMethods;
```

#### `vfChartEcharts`

File: `vfunc-chart-echarts.js`

```ts
interface VfChartEchartsProps extends VfChartProps {
  lib?: unknown;
  options?: Record<string, unknown>;
}
function vfChartEcharts(props: VfChartEchartsProps): VfuncInstance & VfChartMethods;
```

#### `vfGridAg`

File: `vfunc-grid-ag.js`

```ts
interface VfGridAgProps<T = any> extends VfGridProps<T> {
  lib?: unknown;
  options?: Record<string, unknown>;
}
function vfGridAg<T = any>(props: VfGridAgProps<T>): VfuncInstance & VfGridMethods<T>;
```

#### `vfGridTabulator`

File: `vfunc-grid-tabulator.js`

```ts
interface VfGridTabulatorProps<T = any> extends VfGridProps<T> {
  lib?: unknown;
  options?: Record<string, unknown>;
}
function vfGridTabulator<T = any>(props: VfGridTabulatorProps<T>): VfuncInstance & VfGridMethods<T>;
```