# OK JS
> **The UI framework you'd actually love to use.**
> No build. No JSX. No bullshit. Just JavaScript.
---
## What makes OK JS different
Most modern frameworks require you to adopt an entire build pipeline, a new file format, or a non-standard templating language before you write a single line of product code. OK JS takes the opposite position:
- **Your HTML is already the template.** Bindings are plain attributes (`@click`, `:value`, `!value`). Text interpolation uses `{{ }}`. No JSX, no compilation to a virtual tree — just the real DOM, wired reactively.
- **No build step required.** Drop the ESM bundle into a `
```
---
## Quick start
```html
Even vibes only.Odd mood.
```
`OK.init(node, context, config)` creates an instance, attaches a reactive scope to `node`, and initializes all bindings in one async call.
---
## Core concepts
### Reactive Proxy engine
All state lives in `OKProxy`-wrapped objects. Call `ok.proxy(obj)` to make any object reactive:
```js
const state = ok.proxy({ user: { name: 'Ada' }, tags: ['ok', 'js'] });
```
Under the hood:
- **`get` trap** — records `(receiver, property)` as a dependency for any currently-tracking watcher.
- **`set` / `deleteProperty` traps** — queue a change record and schedule dispatch.
- **Dispatch model** — changes are batched and flushed via `queueMicrotask → requestAnimationFrame` by default. Every change in a cycle is preserved and delivered in order; nothing is silently collapsed to "final value only".
- **Deep collections** — `Array`, `Map`, and `Set` mutating methods (`push`, `splice`, `set`, `add`, `delete`…) are monkey-patched to flow through the same change queue.
```js
scope.$watch(
() => state.user.name, // dependency collector — runs once, records deps
changes => console.log(changes) // called with the full ordered change record array
);
state.user.name = 'Grace'; // schedules → dispatches → watcher fires
```
Use `await ok.flush()` in tests or coordination code to wait for a full dispatch cycle to complete.
---
### Scopes
Every DOM element OK manages gets a **scope** — the object responsible for lifecycle, bindings, watchers, and context. Scopes are created automatically by `OK.init` and the component system.
| Method | Purpose |
|---|---|
| `$init()` | Hydrate children, run `mounted`, emit lifecycle events |
| `$destroy(remove)` | Tear down children, run `unmount`, clean DOM |
| `$watch(fn, onChange)` | Reactive watcher, auto-stopped on unmount |
| `$observe(proxy, prop, fn)` | Property-specific observer, auto-stopped on unmount |
| `$observeDeep(target, fn)` | Deep observer on any nested change |
| `$memo(fn)` | Memoized reactive computation |
| `$fn(cmd)` | Compile an expression string bound to `$scope`, `$context`, `$vars` |
| `$invoke(name, ...args)` | Call a lifecycle hook by name across all registered handlers |
**Lifecycle order:** `$init` → `mounted` → *(app runs)* → `$destroy` → `unmount` → `unmounted`.
All sync unmount handlers fire before async teardown continues — cleanup is always predictable.
---
### Binding syntax
| Syntax | Type | Example |
|---|---|---|
| `{{ expr }}` | Text interpolation | `Hello {{ name }}` |
| `@event` | Event listener | `@click="count++"` |
| `@event:modifier` | Modified event | `@keydown:ctrl+enter="submit()"` |
| `:prop` | One-way property/attribute bind | `:textContent="label"` |
| `:class` / `:style` | Class/style object or array | `:class="{ active: isOn }"` |
| `!prop` | Two-way bind (inputs) | `!value="username"` |
| `...prop` | Spread object into attrs/props | `...aria-label="label"` |
Two-way binds (`!`) automatically generate an `input` event handler that coerces by `type` — checkbox → `checked`, number/range → `Number(…)`, everything else → `.value`.
---
### Components
Components are plain JavaScript objects (or `.ok.html` single-file modules) registered with `ok.register()`:
```js
// my-counter.ok.js
import { defineComponent } from './ok.esm.min.js';
export default defineComponent({
tag: 'my-counter',
context(scope) {
return scope.$ok.proxy({ count: 0 });
},
template: `
`
});
```
**`.ok.html` single-file components** — HTML-native equivalents of Vue SFCs, parsed at runtime with no compiler required:
```html
```
Components are dynamically imported, cached, and always mounted inside a **crash boundary**. The `` primitive lets you mount by tag name or lazy import path directly in HTML.
---
## Built-in primitives
Registered automatically on every OK instance:
| Tag | Purpose |
|---|---|
| `` / `` | Conditional rendering |
| `` / `` | Switch-case rendering |
| `` | List rendering with keyed diffing |
| `` | Repeat a template N times |
| `` | Logical grouping without a wrapper element |
| `` | Content projection into components |
| `` | Dynamic component mounting |
| `` | Mount inside a Shadow DOM root |
| `` | Scoped context injection |
| `` | Scoped variable declarations |
| `` | Catch errors and render fallback UI |
| `` | Default styled crash fallback |
| `` | App-level crash event bus |
| `` | Full-page fatal error renderer |
| `` | Register shared singleton services |
---
## Toolkit
40+ components registered the moment an OK instance is created. Every toolkit component is a regular OK component — read the source, trim what you don't need.
### Navigation
- `` / `` — client-side routing with path params, wildcards, nested routes, and programmatic navigation
### UI Components
- `` — reactive data table
- `` / `` — accessible dropdown and select
- `` — icon primitive
- `` / modal service — layered modal system with focus trap
- `` — draggable floating windows
- `` / toast service — notification queue
- `` — overlay / backdrop management
- `` — drag-to-resize panels
- `` — virtual scrolling for large lists
- `` — enter/leave CSS transitions
### Interaction
- `` — drag-and-drop with configurable constraints
- `` — flyover / tooltip panels
- `` — element highlight overlays
- `` — right-click context menus
- `` — nested menu system
- `` / popout service — floating panel system
- `` — global keyboard shortcut registry
### Theming
- `` — CSS variable theming engine with preset stacking, dark/light mode, per-component overrides
- `` — visual runtime theme editor
- `` — complete OK Design system (buttons, inputs, typography, layout variables)
### Internationalization
- `` service — reactive translation registry
- `` — runtime translation editor
### Developer Tools
- `` — DOM + scope tree inspector with keyboard navigation
- `` — collapsible reactive JS object tree viewer
- `` / console service — in-app log console
- `` — real-time FPS overlay
- `ok.perfDump()` — scope lifecycle timing table printed to `console.table`
### Editor & Content
- `` — Monaco Editor (VS Code engine) integration
- `` / `` / `` — live code editing and in-page preview
- `` — reactive Markdown rendering
- `` — in-app documentation viewer
- `` — chart component
### Async & Sync
- `` — declarative async state management (loading / error / data states)
- `` — cross-context reactive sync (localStorage, BroadcastChannel, custom adapters)
---
## Instance API
```js
const ok = OK(config);
// or shortcut:
const ok = await OK.init(node, context, config);
ok.register(componentDef); // register a component definition
ok.init(node, context); // initialize a DOM node
ok.destroy(node); // destroy a node and all its scopes
ok.proxy(obj); // create a reactive proxy
ok.flush(); // Promise — resolves after next dispatch cycle
ok.shared; // reactive shared app-wide state object
ok.emit / ok.on / ok.off; // app-level event bus
ok.getScopeById(id); // look up any live scope by ID
ok.perfDump({ sortBy, limit }); // print scope lifecycle perf table
```
### Configuration
```js
OK({
env: 'dev', // 'dev' | 'prod' | 'debug'
crash: {
mode: 'default', // 'default' | 'throw' | 'silent'
},
dom: {
marker: '…', // comment vs empty-text node markers (env-based default)
},
bind: {
remove_bind_attributes: false, // strip @/:/! attrs in prod
},
log: {
console: true,
},
parser: {
self_closing_tag: 'allow', // 'allow' | 'warn' | 'throw'
},
components: { // per-component config, keyed by tag
'ok-icon': { api: null },
},
shared: { … }, // initial shared state seed
})
```
All keys deep-merge with environment-aware defaults — override only what you need.
`parser` was called `component` before 1.3.0; the old spelling still works. Note the
distinction: `parser` configures template parsing, while `components` (plural) holds
settings for individual components, keyed by tag.
---
## Project structure
```
src/
ok.js # Factory entry point
ok-proxy/ # Reactive Proxy engine (OKProxy) — ≈700 lines
ok-scope.js # Scope system (lifecycle, watchers, context)
runtime/ # Binder, component registry, parser, node walker
primitives/ # Built-in primitive components (if, each, slot…)
emitter.js # Lightweight event emitter
timing.js # nextTick, nextFrame, awaitFrame
toolkit/
navigation/ # router (hash + history)
modals/ # modal, window, toast
theming/ # ok-theme, ok-design, theme editor
interaction/ # drag, popout, hotkeys, context menu, flyover…
devtools/ # inspector, console, fps monitor, JS tree
elements/ # table, dropdown, select, icon
editor/ # live shell, live component, live example
i18n/ # i18n service + editor
sync/ # reactive sync service
components/ # monaco, marked, doc-viewer, chart
layout/ # resizer
core/ # overlay, transition, virtualized
apps/
live-editor/ # Standalone in-browser live code editor app
site/ # Documentation site (built with OK JS itself)
site-2/ # Next-gen docs site
docs/ # Markdown documentation source
dev/
dev-server/ # Dev server with HMR
sandbox/ # Isolated feature test pages
```
---
## Developing
```bash
# Build for production
npm run build
# → dist/ok.esm.js dist/ok.esm.min.js
# → dist/ok.iife.js dist/ok.iife.min.js
# → dist/toolkit/ (individual ESM modules, tree-shakeable)
```
The live editor (`apps/live-editor/`) uses a Service Worker to serve local `.ok.js` / `.ok.html` files directly in the browser playground.
---
## IDE support
- `.ok.js` files already inherit JavaScript support because the final extension is `.js`.
- `.ok.html` files already inherit HTML support because the final extension is `.html`.
- `web-types.json` adds JetBrains/WebStorm autocomplete and element discovery for OK primitives, toolkit components, and app-local OK components.
- `defineComponent(...)` adds typed autocomplete for the outer component object in JS/TS-aware editors.
- `src/analysis/` now provides a shared editor-agnostic analysis core for `.ok.html` structure, OK directives, primitive attrs, diagnostics, and completions.
- `dev/ide/jetbrains-plugin/` now contains an initial JetBrains plugin scaffold that calls the shared analysis core through `dev/ide/ok-analysis-cli.mjs`.
Regenerate the metadata after adding or renaming components:
```bash
npm run ide:metadata
```
This improves custom tag completion and navigation in HTML-like contexts. Full semantic completion inside `template: \`...\`` strings in `.ok.js` files would still require a dedicated IDE plugin or language-server-style integration.
If you want better editing inside `.ok.js` template strings today, JetBrains can also use language injection comments:
```js
import { defineComponent } from './ok.esm.min.js';
export default defineComponent({
tag: 'my-card',
template: /* language=HTML */ `