# kob-ui v0.2.3 — complete reference

Generated from the documentation site by scripts/build-llms.mjs. This file is
the whole of it: every option table, every method, every code sample, the icon
list, and the TypeScript declarations. Nothing is abridged, so an assistant
working from this file alone has what the website shows a reader.

Site: https://kob-ui.com · Package: npm i kob-ui · Global: `Kob`

Licence: free for commercial use, no fee and no attribution required.
Modification, reverse engineering and republication are not permitted, and the
shipped bundle is obfuscated on purpose. Write application code against the
public API documented here; do not try to read or patch dist/.

## How to read the examples

Each example is the markup and the script that produce it on the site. The
site runs them with `root` bound to the element holding that example, which is
why they say `root.querySelector(...)` rather than a page-wide id — in an
application, use your own selector. `KOB_SAMPLE.rows(n)` and `KOB_FMT` are the
sample-data helpers the site defines, not part of the library.

# Start

## Installation

kob-ui ships one JavaScript file and one stylesheet. There is nothing to install alongside it and no build step unless you want one.

```bash
npm i kob-ui
```

### Script tag

```html index.html
<link rel="stylesheet" href="node_modules/kob-ui/dist/kob-ui.css">
<script src="node_modules/kob-ui/dist/kob-ui.min.js"></script>
<script>
  Kob.datagrid('#grid', { columns, data });
</script>
```

### Bundler

```js app.js
import Kob from 'kob-ui';
import 'kob-ui/css';

// Named imports work too, and tree-shake in an ESM build.
import { datagrid, dialog, toast } from 'kob-ui';
```

### What is in the package

| File | Format | Use it for |
| --- | --- | --- |
| dist/kob-ui.min.js | IIFE | A plain `<script>` tag. Defines `window.Kob`. |
| dist/kob-ui.js | IIFE | The same, unminified, for debugging. |
| dist/kob-ui.esm.js | ESM | `import` in a bundler. |
| dist/kob-ui.cjs | CommonJS | `require()`. |
| dist/kob-ui.css | CSS | The whole stylesheet, icons included. |
| types/index.d.ts | TypeScript | Picked up automatically. |

> **Browsers.** Chrome/Edge 80+, Firefox 78+, Safari 14+. No polyfills required.

## Creating widgets

Every widget has one accessor. Call it with options to build the widget; call it again with nothing to get the same instance back.

```js
// Build it. The target may be a selector string or an element.
const grid = Kob.datagrid('#orders', { columns, url: '/api/orders' });

// Anywhere else, later — same object, no bookkeeping.
Kob.datagrid('#orders').reload();

// Passing options to an existing widget merges them and refreshes it.
Kob.datagrid('#orders', { pageSize: 100 });

// Or keep it explicit.
Kob.instance(document.querySelector('#orders'), 'datagrid');
```

Methods return the instance where there is nothing else to return, so they chain: `grid.search('bangkok').gotoPage(1)`.

### Events

Callbacks are options, named `onSomething`. Inside one, `this` is the widget's element.

```js
Kob.datagrid('#orders', {
  onClickRow: (index, row) => select(row),
  onLoadSuccess: function () { console.log(this.id, 'loaded'); }
});
```

### Cleanup

`destroy()` unbinds listeners and puts the DOM back roughly as it was. `Kob.unparse(root)` does it for everything under an element — worth calling before you tear a screen out of the page.

## Markup and data-options

A widget can also be declared in HTML. `Kob.parse(root)` walks the markup and builds anything whose class names a widget.

```html
<input class="kob-textbox" data-options="label:'Name',labelWidth:110,required:true">
<div class="kob-panel"   data-options="title:'Summary',collapsible:true">…</div>
```

```js
Kob.parse(document);            // build everything on the page
Kob.parse(myFragment);          // …or just what you injected
Kob.autoParse();                // build on DOMContentLoaded
```

Parsing twice is safe: an element that already carries a widget is skipped, so you can call it again after injecting HTML.

> **The two can be combined.** Declare the layout in markup, then hand the real configuration over from JavaScript — the widget merges it and rebuilds. That is how a datagrid declared as `class="kob-datagrid"` picks up its columns later.

### What data-options accepts

Quoted strings, numbers, `true`, `false` and `null`. Functions, formatters and column arrays have no sensible text form, so pass those from JavaScript.

## Loading remote data

`combobox` and `datagrid` both take a `url`. Everything they fetch goes through one function, so authentication and response shapes are configured once for the whole library.

```js bootstrap.js
Kob.config.request = async (url, params) => {
  const query = new URLSearchParams(params ?? {});
  const res = await fetch(`${url}?${query}`, {
    headers: { Authorization: `Bearer ${token}` }
  });
  if (res.status === 401) { location.href = '/login'; return []; }

  const payload = await res.json();
  if (!payload.success) { throw new Error(payload.message); }
  return payload.data;          // an array, or { rows, total }
};

// Called whenever the above rejects.
Kob.config.onRequestError = (err, url) => reportToSentry(err, url);
```

A single widget can still reshape its own payload with `loadFilter`.

**Example — Loading from an API**

```html
<div class="ex-grid" style="height:280px"></div>
```

```js
// Kob.config.request is the single place the library talks to a
// server. Replace it once and every widget follows — headers, an
// envelope to unwrap, a redirect on 401.
//
// Kob.config.request = function (url, params) {
//   return fetch(url + new URLSearchParams(params || {}), {
//     headers: { Authorization: 'Bearer ' + token }
//   }).then(function (res) {
//     if (res.status === 401) { location.href = '/login'; return []; }
//     return res.json();
//   }).then(function (payload) {
//     if (!payload.success) { throw new Error(payload.message); }
//     return payload.data;          // an array, or { rows, total }
//   });
// };

// Stubbed here so the page needs no backend of its own.
Kob.config.request = function () {
  return new Promise(function (resolve) {
    setTimeout(function () { resolve({ rows: KOB_SAMPLE.rows(60) }); }, 700);
  });
};

Kob.datagrid(root.querySelector('.ex-grid'), {
  columns: [
    { field: 'room',   title: 'Room',   width: 90 },
    { field: 'tenant', title: 'Tenant', width: 170 },
    { field: 'rent',   title: 'Rent',   width: 110, align: 'right', formatter: KOB_FMT.money }
  ],
  url: '/api/invoices',
  queryParams: { year: 2026 },
  pageSize: 20,
  onLoadSuccess: function () { Kob.toast({ msg: 'Loaded', type: 'info' }); }
});
```

## Theming

Nothing in the stylesheet hard-codes a colour. Redefine the tokens on `:root` — or on any container — and everything inside follows.

```css theme.css
:root {
  --kob-accent: #6d3bd4;
  --kob-accent-dark: #4c2597;
  --kob-accent-soft: rgba(109, 59, 212, 0.09);
  --kob-radius: 14px;
}
```

| Token | Used for |
| --- | --- |
| --kob-accent | Primary buttons, selection, focus rings, active tabs |
| --kob-accent-dark | Header text, sorted column, emphasis on the accent |
| --kob-accent-soft | Headers, hovers, striped rows, chip backgrounds |
| --kob-accent-hover | The stronger hover state |
| --kob-surface / --kob-surface-2 | Panels, windows, dropdowns |
| --kob-bg | The ground the widgets sit on |
| --kob-text / --kob-muted | Body text, secondary text |
| --kob-border / --kob-border-soft | Outlines, table rules |
| --kob-danger / --kob-success / --kob-warn / --kob-info | Status colours and badges |
| --kob-radius / --kob-radius-sm / --kob-radius-xs | Corner rounding |
| --kob-shadow-1 / -2 / -3 | Cards, dropdowns, windows |
| --kob-scrollbar-thumb / -hover / -track / -size | Scrollbars — see below |

### Scrollbars

The browser's own scrollbars are a fixed grey that reads as a foreign object on a dark surface, so every box the library scrolls gets one painted from the tokens instead — vertical, horizontal, and the corner where the two meet. Anything scrolling *inside* a window, panel or layout matches too.

To carry the same treatment to the rest of the page, put the class on the root element:

```html
<html class="kob-scrollbars">
```

A region that keeps its own colours — a dark code panel on a light page, say — just redefines the tokens locally:

```css
.code {
  --kob-scrollbar-thumb: rgba(207, 228, 236, 0.26);
  --kob-scrollbar-thumb-hover: rgba(207, 228, 236, 0.45);
}
```

### The three themes

Three palettes ship. Leave the attribute off and the library follows the operating system, choosing between `light` and `dark`; set it and that choice is pinned.

| Value | What it looks like |
| --- | --- |
| light | The default. Cool greys on white. |
| dark | Blue-grey night theme, surfaces from `#0b1e27` up. |
| black | Neutral near-black with no colour cast — surfaces from `#0f1011`, and the header and hover washes are white at low alpha rather than a tinted accent, so nothing goes blue. Deliberately not `#000`: pure black under near-white text is the highest contrast a panel can make, which reads as glare in a dim room. |

```html
<html data-kob-theme="black">    <!-- or "dark", or "light" -->
```

Switching at runtime is one attribute. Remembering the choice is on you — the library never writes to storage:

```js
var THEMES = ['light', 'dark', 'black'];

function nextTheme() {
  var here = document.documentElement.getAttribute('data-kob-theme') || 'light';
  var next = THEMES[(THEMES.indexOf(here) + 1) % THEMES.length];
  document.documentElement.setAttribute('data-kob-theme', next);
  localStorage.setItem('theme', next);
}

// Restore before the first paint, or the page flashes the wrong theme.
var saved = localStorage.getItem('theme');
if (saved) { document.documentElement.setAttribute('data-kob-theme', saved); }
```

A fourth theme is a block of your own. Only the tokens that differ need redefining — everything else falls through to the light values:

```css
:root[data-kob-theme="sepia"] {
  --kob-bg: #f4ecdf;
  --kob-surface: #fbf6ec;
  --kob-text: #3b3026;
  --kob-accent: #8a5a2b;
}
```

**Example — Retheming with three variables**

```html
<div id="ex-theme" style="padding:18px;border-radius:12px;border:1px solid var(--kob-border)">
  <div style="display:flex;flex-wrap:wrap;gap:8px;margin-bottom:14px">
    <a class="kob-linkbutton kob-linkbutton-primary icon-save"><span class="kob-icon"></span>Save</a>
    <a class="kob-linkbutton icon-add"><span class="kob-icon"></span>Add</a>
    <input type="checkbox" class="kob-checkbox" data-options="label:'Active',checked:true">
  </div>
  <div class="ex-grid" style="height:190px"></div>
</div>
<div style="display:flex;flex-wrap:wrap;gap:8px;margin-top:12px">
  <a class="kob-linkbutton" data-accent="#17607a">Teal</a>
  <a class="kob-linkbutton" data-accent="#6d3bd4">Violet</a>
  <a class="kob-linkbutton" data-accent="#b3401f">Rust</a>
  <a class="kob-linkbutton" data-accent="#1c6b40">Forest</a>
</div>
```

```js
Kob.datagrid(root.querySelector('.ex-grid'), {
  columns: [
    { field: 'room',   title: 'Room',   width: 90 },
    { field: 'tenant', title: 'Tenant', width: 160 },
    { field: 'rent',   title: 'Rent',   width: 110, align: 'right', formatter: KOB_FMT.money }
  ],
  data: KOB_SAMPLE.rows(20),
  pagination: false,
  filterable: false
});

// Nothing in the stylesheet hard-codes a colour, so overriding the
// accent tokens on any element retheme everything inside it.
var scope = root.querySelector('#ex-theme');
root.querySelectorAll('[data-accent]').forEach(function (btn) {
  btn.onclick = function () {
    var accent = btn.getAttribute('data-accent');
    scope.style.setProperty('--kob-accent', accent);
    scope.style.setProperty('--kob-accent-dark', shade(accent, -0.25));
    scope.style.setProperty('--kob-accent-soft', accent + '18');
    scope.style.setProperty('--kob-accent-hover', accent + '2b');
  };
});

function shade(hex, amount) {
  var n = parseInt(hex.slice(1), 16);
  var c = [n >> 16, (n >> 8) & 255, n & 255].map(function (v) {
    return Math.max(0, Math.min(255, Math.round(v + v * amount)));
  });
  return 'rgb(' + c.join(',') + ')';
}
```

## Localisation

Every string the widgets show, plus the date format and calendar era, comes from the active locale. English and Thai are built in.

```js
Kob.locale('th');                     // switch
Kob.locale();                         // read the current one
Kob.t('showing', { from: 1, to: 20, total: 93 });

Kob.addLocale('de', {
  ok: 'OK', cancel: 'Abbrechen', today: 'Heute',
  months: ['Januar', 'Februar', /* … */],
  weekdaysShort: ['So', 'Mo', 'Di', 'Mi', 'Do', 'Fr', 'Sa'],
  firstDay: 1,
  dateFormat: 'dd.mm.yyyy'
});
Kob.locale('de');                     // gaps fall back to English
```

> **Dates stay ISO.** A Thai locale shows `09/03/2567` on screen, but `datebox.getValue()` still returns `'2024-03-09'`. The calendar in use never changes what you send to the server.

The [datebox example](https://kob-ui.com/docs.html#datebox) further down switches between English and Thai live, and reports both what is on screen and what `getValue()` returns.

## Icons

181 single-colour SVGs applied as a CSS mask. They take the element's `color`, live inside the stylesheet, and cost no requests.

```html
<a class="kob-linkbutton icon-add"><span class="kob-icon"></span>Add</a>
```

```js
Kob.linkbutton('#btn', { iconCls: 'icon-add', text: 'Add' });
```

The full set — click any icon to copy its class name:

All 181 class names: icon-add, icon-minus, icon-edit, icon-remove, icon-ok, icon-cancel, icon-close, icon-save, icon-reload, icon-undo, icon-redo, icon-search, icon-filter, icon-print, icon-cut, icon-copy, icon-paste, icon-duplicate, icon-archive, icon-restore, icon-history, icon-sync, icon-pin, icon-bookmark, icon-flag, icon-tag, icon-link, icon-unlink, icon-share, icon-attach, icon-send, icon-chevron-left, icon-chevron-right, icon-chevron-up, icon-chevron-down, icon-back, icon-forward, icon-arrow-up, icon-arrow-down, icon-first, icon-last, icon-external, icon-expand, icon-collapse, icon-fullscreen, icon-fullscreen-exit, icon-zoom-in, icon-zoom-out, icon-drag, icon-grid-view, icon-list-view, icon-columns, icon-sidebar, icon-dashboard, icon-apps, icon-table, icon-sliders, icon-sort, icon-sort-asc, icon-sort-desc, icon-list-check, icon-hash, icon-sum, icon-menu, icon-more, icon-folder, icon-folder-open, icon-folder-plus, icon-file, icon-file-text, icon-file-pdf, icon-file-word, icon-file-csv, icon-file-code, icon-file-image, icon-file-zip, icon-excel, icon-cloud, icon-cloud-upload, icon-cloud-download, icon-database, icon-server, icon-download, icon-upload, icon-mail, icon-inbox, icon-chat, icon-comment, icon-bell, icon-bell-off, icon-phone, icon-video, icon-mic, icon-mic-off, icon-at, icon-cart, icon-bag, icon-box, icon-truck, icon-store, icon-receipt, icon-invoice, icon-credit-card, icon-wallet, icon-coins, icon-banknote, icon-percent, icon-gift, icon-user, icon-users, icon-user-plus, icon-user-check, icon-user-x, icon-id-card, icon-key, icon-lock, icon-unlock, icon-shield, icon-shield-check, icon-login, icon-logout, icon-tip, icon-warn, icon-question, icon-check-circle, icon-x-circle, icon-ban, icon-verified, icon-thumbs-up, icon-heart, icon-star, icon-bolt, icon-hourglass, icon-clock, icon-calendar, icon-eye, icon-eye-off, icon-chart, icon-chart-line, icon-chart-pie, icon-trending-up, icon-trending-down, icon-activity, icon-monitor, icon-laptop, icon-mobile, icon-keyboard, icon-wifi, icon-wifi-off, icon-battery, icon-power, icon-terminal, icon-code, icon-bug, icon-scan, icon-qr, icon-play, icon-pause, icon-stop, icon-skip-back, icon-skip-forward, icon-volume, icon-volume-off, icon-camera, icon-image, icon-palette, icon-home, icon-building, icon-map-pin, icon-map, icon-globe, icon-briefcase, icon-clipboard, icon-clipboard-check, icon-book, icon-note, icon-calculator, icon-settings, icon-sun, icon-moon, icon-contrast

Your own artwork works the same way, without touching the library — point the mask at your SVG:

```css
.icon-invoice .kob-icon {
  -webkit-mask-image: url(/img/invoice.svg);
          mask-image: url(/img/invoice.svg);
}
```

# Form widgets

## textbox, numberbox, passwordbox

Three thin wrappers over `<input>`: an optional label, a required flag, and for numbers, clamping and formatting.

**Example — Text, number and password**

```html
<form style="max-width:440px" onsubmit="return false">
  <input class="kob-textbox"     name="tenant" data-options="label:'Tenant',labelWidth:110,prompt:'Full name'">
  <input class="kob-numberbox"   name="rent"   data-options="label:'Rent',labelWidth:110,precision:2,min:0,groupSeparator:','">
  <input class="kob-passwordbox" name="pin" autocomplete="current-password" data-options="label:'PIN',labelWidth:110">
  <div style="text-align:right"><a class="kob-linkbutton icon-tip" id="ex-read"><span class="kob-icon"></span>Read values</a></div>
</form>
```

```js
var rent = Kob.numberbox(root.querySelector('.kob-numberbox'));
rent.setValue(12500);   // shown as 12,500.00, read back as a number

root.querySelector('#ex-read').onclick = function () {
  Kob.alert({
    title: 'Values',
    msg: 'tenant: ' + Kob.textbox(root.querySelector('.kob-textbox')).getValue() +
         '\nrent: ' + rent.getValue() + ' (' + typeof rent.getValue() + ')'
  });
};
```

### Options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| label | string | `''` | Draws a label next to the field. Omit for a bare input. |
| labelWidth | number | `110` | Label width in pixels when it sits to the left. |
| labelPosition | 'left' \| 'top' | auto | Defaults to `top` on touch screens, `left` otherwise. |
| prompt | string | `''` | Placeholder text. |
| value | any | — | Initial value. |
| required | boolean | `false` | Checked by `isValid()` and by the containing form. |
| readonly / disabled | boolean | — | Applied to the underlying input. |
| min / max | number | — | *numberbox*: clamped on blur. |
| precision | number | — | *numberbox*: decimal places applied on blur. |
| groupSeparator | string | `''` | *numberbox*: thousands separator shown while unfocused. |
| onChange | function(value) | — | Fires on the input's native change. |

### Methods

| Method | Returns | Description |
| --- | --- | --- |
| getValue() | string \| number | numberbox returns a number, or `''` when empty. |
| setValue(v) | this | numberbox also clamps and formats. |
| clear() | this | Empties the field and drops the invalid mark. |
| isValid() | boolean | Whether `required` is satisfied. |
| enable() / disable() | this |   |
| readonly(mode) | this |   |
| focus() | this |   |

## combobox

A text input backed by a list. The value the form submits and the text the user reads are kept apart, so an id column never leaks onto screen.

**Example — Combobox**

```html
<div style="max-width:440px">
  <input class="kob-combobox" id="ex-cb-room" data-options="label:'Room',labelWidth:110,editable:false">
  <input class="kob-combobox" id="ex-cb-type" data-options="label:'Type',labelWidth:110,prompt:'type to filter'">
  <p style="margin:8px 0 0;color:var(--kob-muted);font-size:13.5px" id="ex-cb-out">nothing picked yet</p>
</div>
```

```js
var out = root.querySelector('#ex-cb-out');

// Pick from the list only — typing does not filter.
Kob.combobox(root.querySelector('#ex-cb-room'), {
  data: KOB_SAMPLE.rows(24).map(function (r) {
    return { id: r.id, text: r.room + ' — ' + r.tenant };
  }),
  value: 3,
  onChange: function (value, row) {
    out.textContent = 'value ' + value + '  ·  text "' + row.text + '"';
  }
});

// Editable: typing filters, and a formatter may return HTML.
Kob.combobox(root.querySelector('#ex-cb-type'), {
  valueField: 'code',
  textField: 'name',
  data: [
    { code: 'studio', name: 'Studio',    size: 24 },
    { code: '1br',    name: '1 bedroom', size: 32 },
    { code: '2br',    name: '2 bedroom', size: 48 },
    { code: 'duplex', name: 'Duplex',    size: 64 }
  ],
  formatter: function (row) {
    return row.name + ' <small style="color:var(--kob-muted)">' + row.size + ' m²</small>';
  }
});
```

### Options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| data | object[] | `null` | Rows to show. |
| url | string | `''` | Fetched through `Kob.config.request`. |
| queryParams | object | `null` | Sent with the request. |
| valueField | string | `'id'` | Field `getValue()` returns. |
| textField | string | `'text'` | Field shown in the box. |
| formatter | function(row) | — | HTML for one list item. The box shows its plain text. |
| editable | boolean | `true` | `false` means pick from the list only. |
| panelHeight | number | `300` | Maximum dropdown height in pixels. |
| limit | number | `300` | Items rendered at once; the rest are reachable by typing. |
| label / labelWidth / prompt / required | — | — | As for [textbox](https://kob-ui.com/docs.html#textbox). |
| onChange | function(value, row) | — | After a pick. |
| onSelect | function(row) | — | The row that was clicked. |
| onLoadSuccess | function(rows) | — | After `loadData` or a fetch. |

### Methods

| Method | Returns | Description |
| --- | --- | --- |
| getValue() / setValue(v) | any / this | The `valueField` value. |
| getText() | string | What the user reads. |
| loadData(rows) | this | Swap the list without touching the value. |
| reload(url?) | Promise | Fetch again, optionally from a new URL. |
| getData() | object[] | The current list. |
| clear() | this |   |

**Keyboard:** arrows move through the list, Enter picks, Escape closes.

## datebox

A text field with a month calendar. It reads and writes ISO dates whatever the locale displays.

**Example — Date picker and the Buddhist calendar**

```html
<div style="max-width:440px">
  <input class="kob-datebox" id="ex-date" data-options="label:'Move in',labelWidth:110">
  <div style="display:flex;gap:8px;margin-bottom:10px">
    <a class="kob-linkbutton" id="ex-en">English</a>
    <a class="kob-linkbutton" id="ex-th">ไทย (พ.ศ.)</a>
  </div>
  <p style="margin:0;color:var(--kob-muted);font-size:13.5px" id="ex-date-out"></p>
</div>
```

```js
var box = Kob.datebox(root.querySelector('#ex-date'), {
  value: '2026-03-09',
  onChange: report
});

function report() {
  root.querySelector('#ex-date-out').textContent =
    'on screen: ' + box.getText() + '   ·   getValue(): ' + box.getValue();
}

// The locale decides the display format and the era. The value the
// application reads is ISO yyyy-mm-dd either way.
function relocalise(name) {
  var iso = box.getValue();
  Kob.locale(name);
  box.setValue(iso);
  report();
}
root.querySelector('#ex-en').onclick = function () { relocalise('en'); };
root.querySelector('#ex-th').onclick = function () { relocalise('th'); };
report();
```

### Options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| value | string \| Date | — | ISO, a Date, or a string in the display format. |
| format | string | locale | Overrides the locale's format, from `yyyy`, `yy`, `mm`, `dd`. |
| min / max | string | `''` | ISO bounds; days outside them are disabled. |
| showToday | boolean | `true` | The shortcut under the calendar. |
| label / labelWidth / prompt / required | — | — | As for [textbox](https://kob-ui.com/docs.html#textbox). |
| onChange / onSelect | function(iso) | — | Both receive the ISO date. |

### Methods

| Method | Returns | Description |
| --- | --- | --- |
| getValue() | string | ISO `yyyy-mm-dd`, or `''`. |
| setValue(v) | this | Accepts ISO, a Date, or the display format. |
| getText() | string | What is on screen, e.g. `09/03/2567`. |
| clear() | this |   |

## checkbox

A real `<input type="checkbox">` drawn as a switch, so forms submit it and `getValue()` is simply its checked state.

**Example — Checkbox switch**

```html
<div style="display:flex;flex-direction:column;gap:12px;max-width:380px">
  <input type="checkbox" class="kob-checkbox" data-options="label:'Tenant is active',checked:true">
  <input type="checkbox" class="kob-checkbox" id="ex-cb-mail" data-options="label:'Email the receipt'">
  <input type="checkbox" class="kob-checkbox" data-options="label:'Locked by the auditor',disabled:true,checked:true">
</div>
```

```js
// A real <input type="checkbox"> stays in the DOM, so forms submit it
// and getValue() is just its checked state.
Kob.checkbox(root.querySelector('#ex-cb-mail'), {
  onChange: function (checked) {
    Kob.toast({ msg: checked ? 'Receipt will be emailed' : 'No email', type: 'info' });
  }
});
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| label | string | `''` | Caption beside the switch; also its accessible name. |
| checked | boolean | — | Initial state. |
| disabled | boolean | — |   |
| onChange | function(checked) | — |   |

**Methods:** `getValue()`, `setValue(v)`, `check()`, `uncheck()`, `toggle()`, `enable()`, `disable()`.

## searchbox

A text input that looks and behaves like a search field: a magnifier on the left, a clear button that appears once there is something to clear, Escape to empty it, and `onSearch` debounced so holding a key down costs one search rather than twenty.

```html
<input class="kob-searchbox" data-options="prompt:'Room or tenant'">
```

```js
Kob.searchbox('#find', {
  delay: 250,                       // ms of quiet before onSearch fires
  onSearch: function (q) { grid.search(q); },
  onClear: function () { grid.search(''); }
});
```

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| delay | number | `300` | Milliseconds of quiet before onSearch fires. `0` fires on every keystroke. |
| searchOnEnter | boolean | `false` | Never search while typing — only on Enter or the clear button. |
| clearable | boolean | `true` | Show the clear button once the field has a value. |
| onSearch | function | `null` | Receives the query, already trimmed. |
| onClear | function | `null` | Fires when the field is emptied by the button or by Escape. |

It inherits `label`, `labelWidth`, `prompt` and the rest from [textbox](https://kob-ui.com/docs.html#textbox). Methods: `getValue()` (trimmed), `setValue()`, `clear()`, `search(value?)` — which runs `onSearch` immediately, ignoring both the debounce and the guard that skips an unchanged query.

**Example — Search box**

```html
<div style="display:flex;gap:10px;flex-wrap:wrap;align-items:center;margin-bottom:12px">
  <input class="kob-searchbox" id="sx-find" style="width:260px" data-options="prompt:'Room, tenant or building'">
  <span class="kob-muted" id="sx-out" style="font-size:13px"></span>
</div>
<div id="sx-grid" style="height:260px"></div>
```

```js
var rows = KOB_SAMPLE.rows(84);
var out = root.querySelector('#sx-out');

var grid = Kob.datagrid(root.querySelector('#sx-grid'), {
  columns: [
    { field: 'room',     title: 'Room',     width: 80 },
    { field: 'tenant',   title: 'Tenant',   width: 140 },
    { field: 'building', title: 'Building', width: 120 },
    { field: 'rent',     title: 'Rent',     width: 100, align: 'right', formatter: KOB_FMT.money }
  ],
  data: rows,
  filterable: false,
  searchable: false,
  pageSize: 20
});

// onSearch is debounced, so holding a key down costs one search, not
// twenty. Enter and the clear button skip the wait.
Kob.searchbox(root.querySelector('#sx-find'), {
  delay: 200,
  onSearch: function (q) {
    grid.search(q);
    out.textContent = q
      ? grid.getVisibleRows().length + ' of ' + rows.length + ' match “' + q + '”'
      : '';
  }
});
```

## filebox

A drop zone and a file list. Drag files onto it or click to browse; it checks them against `accept`, `maxSize` and `maxFiles`, lists what survived, and — if you give it a `url` — uploads each one with a progress bar.

```html
<div class="kob-filebox" data-options="accept:'.pdf,.png',maxSize:2000000"></div>
```

```js
var box = Kob.filebox('#docs', {
  accept: '.pdf,image/*',
  maxSize: 2 * 1024 * 1024,
  url: '/api/upload',
  fieldName: 'document',
  data: { tenantId: 42 },
  onProgress: function (file, percent) { … },
  onComplete: function (ok, failed) { … }
});

box.upload();                       // returns a Promise<{ ok, failed }>
```

> url
>
> getFiles()
>
> FormData

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| multiple | boolean | `true` | Accept more than one file. |
| accept | string | `''` | Extensions and MIME patterns: `'.pdf,image/*'`. |
| maxSize | number | `0` | Bytes per file. `0` means no limit. |
| maxFiles | number | `0` | How many may be queued at once. |
| url | string | `''` | POST target. Empty leaves it a picker. |
| fieldName | string | `'file'` | Form field name each file is sent under. |
| data | object | `null` | Extra form fields sent with every file. |
| headers | object | `null` | Request headers, e.g. an Authorization token. |
| autoUpload | boolean | `false` | Upload as soon as a file is added. |
| text / hint | string | `''` | Drop-zone caption and sub-line. Both default to the locale strings. |
| onAdd / onRemove | function | `null` | `(file)`. |
| onProgress | function | `null` | `(file, percent)` while uploading. |
| onSuccess | function | `null` | `(file, response)` — parsed as JSON when it is JSON. |
| onError | function | `null` | `(file, message)` — also fires for a file the rules turned away. |
| onComplete | function | `null` | `(ok, failed)` once every queued file has finished. |

Methods: `add(files)`, `remove(index)`, `clear()`, `getFiles()`, `getItems()` (each with its status and percent), `upload()`, `enable()` / `disable()`.

Uploads go through `XMLHttpRequest` rather than `fetch`, because fetch still cannot report upload progress — and the progress bar is most of the point of a file field. One request per file, so a single failure does not lose the batch.

**Example — File upload**

```html
<div class="kob-row">
  <div class="kob-col-7">
    <div id="up-box"></div>
    <div style="display:flex;gap:8px;margin-top:12px">
      <a class="kob-linkbutton kob-linkbutton-primary icon-cloud-upload" id="up-send"><span class="kob-icon"></span>Upload</a>
      <a class="kob-linkbutton icon-remove" id="up-clear"><span class="kob-icon"></span>Clear</a>
    </div>
  </div>
  <div class="kob-col-5">
    <div class="kob-alert kob-alert-info" style="margin:0">
      <div class="kob-alert-title">This page has no server</div>
      <div class="kob-alert-body">Uploading really does POST to <code>/api/upload</code>, which is not there — so you get the progress bar and then the error state, both genuine.</div>
    </div>
    <pre id="up-out" style="margin-top:12px;font-size:12px;color:var(--kob-muted);white-space:pre-wrap"></pre>
  </div>
</div>
```

```js
var out = root.querySelector('#up-out');

var box = Kob.filebox(root.querySelector('#up-box'), {
  accept: '.pdf,.png,.jpg,.csv',
  maxSize: 2 * 1024 * 1024,
  maxFiles: 5,
  url: '/api/upload',
  fieldName: 'document',
  data: { tenantId: 42 },

  onAdd: function (file) { show(); },
  onRemove: function () { show(); },
  onProgress: function (file, percent) {
    out.textContent = file.name + ' — ' + percent + '%';
  },
  onError: function (file, why) {
    Kob.toast({ msg: file.name + ': ' + why, type: 'error' });
  },
  onComplete: function (ok, failed) {
    Kob.sweet[failed ? 'error' : 'success'](
      failed ? 'Upload failed' : 'Uploaded',
      ok + ' succeeded, ' + failed + ' failed.'
    );
    show();
  }
});

function show() {
  var files = box.getFiles();
  out.textContent = files.length
    ? files.map(function (f) { return f.name + '  (' + f.size + ' bytes)'; }).join('\n')
    : 'nothing queued';
}
show();

root.querySelector('#up-send').onclick = function () {
  if (!box.getFiles().length) {
    return Kob.sweet.warn('Nothing to upload', 'Add a file first.');
  }
  box.upload();
};

root.querySelector('#up-clear').onclick = function () { box.clear(); show(); };

// Leave 'url' out and the widget never touches the network: it just
// collects files, and box.getFiles() hands them to your own FormData.
```

## linkbutton

Turns an `<a>` or `<button>` into a toolbar button with an icon.

**Example — Buttons and icons**

```html
<div style="display:flex;flex-wrap:wrap;gap:8px;align-items:center">
  <a class="kob-linkbutton kob-linkbutton-primary icon-save"><span class="kob-icon"></span>Save</a>
  <a class="kob-linkbutton icon-add">        <span class="kob-icon"></span>Add</a>
  <a class="kob-linkbutton icon-edit">       <span class="kob-icon"></span>Edit</a>
  <a class="kob-linkbutton icon-remove">     <span class="kob-icon"></span>Delete</a>
  <a class="kob-linkbutton icon-print" data-options="disabled:true"><span class="kob-icon"></span>Print</a>
  <a class="kob-linkbutton icon-filter" id="ex-toggle"><span class="kob-icon"></span>Filter</a>
</div>
```

```js
// Markup with a kob-* class is built by Kob.parse(). Reach an
// existing widget again by asking for it with no options.
Kob.linkbutton(root.querySelector('#ex-toggle'), {
  toggle: true,
  onClick: function () {
    Kob.toast('Filter ' + (Kob.linkbutton(this).isSelected() ? 'on' : 'off'));
  }
});
```

### Colours

Five colours, in two weights. **Solid** is for the one action a screen is really about — Save, Delete. **Soft** is the same meaning at a fraction of the weight, for the row of secondary actions beside it, so a toolbar of six buttons does not end up shouting six things at once.

```html
<a class="kob-linkbutton kob-linkbutton-danger">Delete</a>
<a class="kob-linkbutton kob-linkbutton-danger kob-linkbutton-soft">Delete</a>
```

```js
Kob.linkbutton('#save', { text: 'Save', iconCls: 'icon-save', color: 'accent' });
Kob.linkbutton('#del',  { text: 'Delete', color: 'danger', soft: true });
```

| color | Class | For |
| --- | --- | --- |
| `'accent'` | kob-linkbutton-accent | The main action. `primary: true` is the older spelling of the same thing. |
| `'success'` | kob-linkbutton-success | Approve, confirm, mark done. |
| `'danger'` | kob-linkbutton-danger | Delete, and anything else that cannot be undone. |
| `'warn'` | kob-linkbutton-warn | Void, reverse, override. |
| `'info'` | kob-linkbutton-info | Send, export, anything informational. |

Add `soft: true` or `kob-linkbutton-soft` for the tonal version. The same five work on a plain `<button class="kob-btn kob-btn-danger">` with no JavaScript at all.

> --kob-danger-solid
>
> --kob-on-danger
>
> --kob-danger
>
> text
>
> --kob-danger-text

**Example — Button colours**

```html
<p class="kob-muted" style="margin:0 0 10px;font-size:13.5px">Solid — for the one action a screen is about.</p>
<div style="display:flex;flex-wrap:wrap;gap:8px;align-items:center;margin-bottom:20px">
  <a class="kob-linkbutton kob-linkbutton-accent icon-save"><span class="kob-icon"></span>Save</a>
  <a class="kob-linkbutton kob-linkbutton-success icon-check-circle"><span class="kob-icon"></span>Approve</a>
  <a class="kob-linkbutton kob-linkbutton-danger icon-remove"><span class="kob-icon"></span>Delete</a>
  <a class="kob-linkbutton kob-linkbutton-warn icon-warn"><span class="kob-icon"></span>Void</a>
  <a class="kob-linkbutton kob-linkbutton-info icon-send"><span class="kob-icon"></span>Send</a>
  <a class="kob-linkbutton"><span class="kob-icon icon-close"></span>Plain</a>
</div>
<p class="kob-muted" style="margin:0 0 10px;font-size:13.5px">Soft — the same meanings, for a toolbar that has several of them.</p>
<div style="display:flex;flex-wrap:wrap;gap:8px;align-items:center;margin-bottom:20px">
  <a class="kob-linkbutton kob-linkbutton-accent kob-linkbutton-soft icon-edit"><span class="kob-icon"></span>Edit</a>
  <a class="kob-linkbutton kob-linkbutton-success kob-linkbutton-soft icon-ok"><span class="kob-icon"></span>Mark paid</a>
  <a class="kob-linkbutton kob-linkbutton-danger kob-linkbutton-soft icon-remove"><span class="kob-icon"></span>Delete</a>
  <a class="kob-linkbutton kob-linkbutton-warn kob-linkbutton-soft icon-history"><span class="kob-icon"></span>Reverse</a>
  <a class="kob-linkbutton kob-linkbutton-info kob-linkbutton-soft icon-download"><span class="kob-icon"></span>Export</a>
</div>
<p class="kob-muted" style="margin:0 0 10px;font-size:13.5px">Built from JavaScript, and a plain <code>&lt;button class="kob-btn"&gt;</code>.</p>
<div style="display:flex;flex-wrap:wrap;gap:8px;align-items:center">
  <a class="kob-linkbutton" id="bc-js"></a>
  <a class="kob-linkbutton" id="bc-cycle"></a>
  <button class="kob-btn kob-btn-success">kob-btn-success</button>
  <button class="kob-btn kob-btn-danger">kob-btn-danger</button>
  <button class="kob-btn">kob-btn</button>
</div>
```

```js
// The class in the markup and the option are the same thing said two
// ways — Kob.parse reads one, this writes the other.
Kob.linkbutton(root.querySelector('#bc-js'), {
  text: 'From options',
  iconCls: 'icon-bolt',
  color: 'success'
});

var COLORS = ['accent', 'success', 'danger', 'warn', 'info'];
var at = 0;

var cycle = Kob.linkbutton(root.querySelector('#bc-cycle'), {
  text: 'color: accent',
  iconCls: 'icon-palette',
  color: 'accent',
  onClick: function () {
    at = (at + 1) % COLORS.length;
    cycle.option({ color: COLORS[at], text: 'color: ' + COLORS[at] });
  }
});

// The five come from --kob-<name>-solid and --kob-on-<name>, a pair per
// colour, so the label stays legible in all three themes. Try the theme
// switch at the top of the page.
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| text | string | — | Caption. Omit to keep what is already in the tag. |
| iconCls | string | `''` | e.g. `'icon-save'`. See [Icons](https://kob-ui.com/docs.html#icons). |
| iconAlign | 'left' \| 'right' | `'left'` |   |
| primary | boolean | `false` | Paints it in the accent colour. |
| plain | boolean | `false` | No border or background until hovered. |
| toggle | boolean | `false` | Behaves as a pressable toggle. |
| selected | boolean | `false` | Toggle state. |
| disabled | boolean | `false` |   |
| onClick | function(event) | — |   |

**Methods:** `setText(s)`, `getText()`, `setIcon(cls)`, `toggle(on?)`, `isSelected()`, `enable()`, `disable()`.

## form

Collects every kob-ui field inside a `<form>` so you can read, fill, validate and clear them in one call — whatever mix of widgets they are.

**Example — Reading and validating a whole form**

```html
<form class="kob-form" id="ex-form" style="max-width:460px">
  <input class="kob-textbox"   name="tenant"  data-options="label:'Tenant',labelWidth:110,required:true">
  <input class="kob-combobox"  name="room"    id="ex-form-room" data-options="label:'Room',labelWidth:110,editable:false,required:true">
  <input class="kob-numberbox" name="rent"    data-options="label:'Rent',labelWidth:110,precision:2">
  <input class="kob-datebox"   name="moveIn"  data-options="label:'Move in',labelWidth:110">
  <input type="checkbox" class="kob-checkbox" name="active" data-options="label:'Active'">
  <div style="display:flex;gap:8px;justify-content:flex-end;margin-top:14px">
    <a class="kob-linkbutton icon-cancel" id="ex-form-clear"><span class="kob-icon"></span>Clear</a>
    <a class="kob-linkbutton icon-ok" id="ex-form-fill"><span class="kob-icon"></span>Fill</a>
    <a class="kob-linkbutton kob-linkbutton-primary icon-save" id="ex-form-save"><span class="kob-icon"></span>Save</a>
  </div>
</form>
<pre style="margin:12px 0 0;padding:10px 12px;border-radius:8px;background:var(--kob-accent-soft);font-size:12.5px" id="ex-form-out">values appear here</pre>
```

```js
Kob.combobox(root.querySelector('#ex-form-room'), {
  data: KOB_SAMPLE.rows(12).map(function (r) { return { id: r.room, text: r.room }; })
});

var form = Kob.form(root.querySelector('#ex-form'));
var out = root.querySelector('#ex-form-out');

// validate() marks every offender and focuses the first one.
root.querySelector('#ex-form-save').onclick = function () {
  out.textContent = form.validate()
    ? JSON.stringify(form.getValues(), null, 1)
    : 'Some required fields are still empty.';
};

root.querySelector('#ex-form-fill').onclick = function () {
  form.setValues({ tenant: 'Somchai P.', room: '104/5', rent: 8500, moveIn: '2026-04-01', active: true });
};
root.querySelector('#ex-form-clear').onclick = function () {
  form.clear();
  out.textContent = 'cleared';
};
```

| Method | Returns | Description |
| --- | --- | --- |
| getValues() | object | Keyed by each field's `name`, read through its widget. |
| setValues(obj) | this | Fills matching fields; unknown keys are ignored. |
| validate() | boolean | Marks offenders with `.kob-invalid` and focuses the first. |
| clear() | this | Empties every field and drops the marks. |

| Option | Type | Description |
| --- | --- | --- |
| markInvalid | boolean | Add `.kob-invalid` to failing fields. Default `true`. |
| onValidate | function(ok, values) | Return `false` to fail validation with your own rule. |
| onSubmit | function(event, values) | Runs after validation passes on a real submit. |

# Containers

## panel

A titled content box that can fold away or load its body from a URL — and parse the widgets in whatever comes back.

**Example — Panel**

```html
<div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:14px">
  <div class="kob-panel" data-options="title:'Summary',iconCls:'icon-chart',collapsible:true">
    <p style="margin:0">Fold me away with the caret.</p>
  </div>
  <div class="kob-panel" id="ex-panel-load" data-options="title:'Loaded from a URL',iconCls:'icon-folder'">
  </div>
</div>
```

```js
// panel.load(url) drops the response HTML into the body and parses
// any widgets it contains. Here the markup is set directly instead,
// which goes through the same parsing step.
Kob.panel(root.querySelector('#ex-panel-load')).setContent(
  '<p style="margin-top:0">Content arrived, and the button below was ' +
  'parsed out of it.</p>' +
  '<a class="kob-linkbutton icon-reload"><span class="kob-icon"></span>Refresh</a>'
);
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| title | string | `''` | Header caption. Omit for a headerless panel. |
| iconCls | string | `''` | Icon in the header. |
| collapsible | boolean | `false` | Shows the fold caret. |
| collapsed | boolean | `false` | Start folded. |
| closable | boolean | `false` | Shows a close button that removes the panel. |
| href | string | `''` | Fetch this URL into the body on init. |
| fit | boolean | `false` | Fill the parent box. |
| border | boolean | `true` |   |
| loadingMessage | string | locale | Shown while `href` is in flight. |
| onLoad / onCollapse / onExpand / onClose | function | — |   |

**Methods:** `getBody()`, `setTitle(s)`, `load(url)`, `setContent(html)`, `collapse()`, `expand()`, `toggleCollapse()`, `close()`.

## layout

The classic five-region frame. Regions are declared on the children; the widget restacks them once so flexbox can do the sizing.

**Example — Layout with a draggable splitter**

```html
<div class="kob-layout" id="ex-layout" style="height:260px;border:1px solid var(--kob-border);border-radius:10px;overflow:hidden">
  <div data-options="region:'north',height:56" style="padding:12px"><b>North</b> — fixed height</div>
  <div data-options="region:'west',width:180,split:true,minSize:120" style="padding:12px"><b>West</b><br>drag my right edge</div>
  <div data-options="region:'center'" style="padding:12px"><b>Center</b> — takes the rest</div>
  <div data-options="region:'south',height:48" style="padding:12px"><b>South</b></div>
</div>
<div style="margin-top:10px;display:flex;gap:8px">
  <a class="kob-linkbutton icon-chevron-left" id="ex-layout-fold"><span class="kob-icon"></span>Fold the west region</a>
</div>
```

```js
var layout = Kob.layout(root.querySelector('#ex-layout'));

root.querySelector('#ex-layout-fold').onclick = function () {
  layout.toggle('west');
};

// layout.panel('center') hands back the region element, so a datagrid
// or anything else can be mounted straight into it.
layout.panel('center').insertAdjacentHTML('beforeend',
  '<p style="color:var(--kob-muted);margin:8px 0 0;font-size:13.5px">' +
  'Regions are plain elements — put whatever you like inside.</p>');
```

### Region options

Set these in each child's `data-options`.

| Option | Type | Description |
| --- | --- | --- |
| region | string | `north`, `south`, `west`, `east` or `center`. Required. |
| width | number | west and east, in pixels. |
| height | number | north and south, in pixels. |
| split | boolean | Adds a draggable splitter on the inner edge. |
| minSize / maxSize | number | Drag limits. |
| collapsible | boolean | Puts a fold button on the splitter. |

**Methods:** `panel(region)` returns the region element, plus `resize(region, px)`, `collapse(region)`, `expand(region)`, `toggle(region)`, `remove(region)`.

**Events:** `onResize(region, size)`, `onCollapse(region)`, `onExpand(region)`.

> A layout fills its parent, so give the parent a height — `height:100%` or a fixed value — or it collapses to nothing.

## tabs

Every direct child carrying a `title` attribute becomes a page.

**Example — Tabs**

```html
<div class="kob-tabs" id="ex-tabs" style="height:190px;border:1px solid var(--kob-border);border-radius:10px;overflow:hidden">
  <div title="Details" style="padding:16px">Any direct child with a <code>title</code> becomes a page.</div>
  <div title="History" style="padding:16px" data-options="closable:true">This one can be closed.</div>
</div>
<div style="margin-top:10px"><a class="kob-linkbutton icon-add" id="ex-tab-add"><span class="kob-icon"></span>Add a tab</a></div>
```

```js
var tabs = Kob.tabs(root.querySelector('#ex-tabs'), {
  onSelect: function (index, title) { Kob.toast('Tab: ' + title); }
});

var n = 0;
root.querySelector('#ex-tab-add').onclick = function () {
  tabs.add({
    title: 'Note ' + (++n),
    content: '<div style="padding:16px">Added at ' + new Date().toLocaleTimeString() + '</div>',
    closable: true
  });
};
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| selected | number | `0` | Index shown first. |
| closable | boolean | `false` | Close buttons on every tab. A page can opt in on its own with `data-options="closable:true"`. |
| onSelect | function(index, title) | — |   |
| onBeforeClose | function(index, title) | — | Return `false` to keep the tab open. |
| onClose / onAdd | function | — |   |

**Methods:** `select(i)`, `selectByTitle(s)`, `getSelected()`, `getPanel(i)`, `getPages()`, `add({ title, content, iconCls, closable })`, `close(i)`.

### Per-page options

A page carries its own settings in `data-options`, next to the title the tab is named after:

```html
<div class="kob-tabs">
  <div title="Details" data-options="iconCls:'icon-user'">…</div>
  <div title="History" data-options="iconCls:'icon-history',closable:true">…</div>
</div>
```

### Three looks

The default is a folder: the selected tab is a raised card that overlaps the strip below it, so it and the page read as one surface. Two classes on the container change that without touching the markup inside.

| Class | Look |
| --- | --- |
| — | The default folder tabs, with an accent cap on the selected one. |
| `kob-tabs-pill` | A segmented control: the selected tab is a filled pill and there is no strip. |
| `kob-tabs-plain` | A flat underline — tabs that get out of the way of the page. |

```html
<div class="kob-tabs kob-tabs-pill">…</div>
```

## stepper

The path through a multi-step task, across the page or down it. Give it children with a `title` and each one becomes a step *and* the panel shown while that step is current; give it none and it is the indicator on its own.

**Example — Stepper — across the page**

```html
<div class="kob-stepper" id="ex-stepper">
  <div title="Tenant" data-options="text:'Who is moving in',iconCls:'icon-user'">
    <form class="kob-form" id="ex-step-form" style="max-width:430px" onsubmit="return false">
      <input class="kob-textbox" name="tenant" data-options="label:'Full name',labelWidth:110,required:true">
      <input class="kob-textbox" name="phone"  data-options="label:'Phone',labelWidth:110">
    </form>
  </div>
  <div title="Room" data-options="text:'Which unit',iconCls:'icon-building'">
    <form class="kob-form" style="max-width:430px" onsubmit="return false">
      <input class="kob-combobox"  name="room" id="ex-step-room" data-options="label:'Room',labelWidth:110,editable:false">
      <input class="kob-numberbox" name="rent" data-options="label:'Rent',labelWidth:110,precision:2,groupSeparator:','">
    </form>
  </div>
  <div title="Confirm" data-options="text:'Check and sign',iconCls:'icon-clipboard'">
    <div class="kob-alert" style="max-width:430px" data-options="type:'info',title:'Ready to issue'">
      Nothing has been saved yet — the button below is what writes the lease.
    </div>
  </div>
</div>

<div style="display:flex;gap:8px;margin-top:18px">
  <a class="kob-linkbutton icon-back" id="ex-step-back"><span class="kob-icon"></span>Back</a>
  <a class="kob-linkbutton kob-linkbutton-primary icon-forward" id="ex-step-next"><span class="kob-icon"></span>Next</a>
  <span style="flex:1"></span>
  <a class="kob-linkbutton icon-reload" id="ex-step-reset"><span class="kob-icon"></span>Start over</a>
</div>
```

```js
// Each child with a title is both a step and the panel shown while
// that step is current — the same idiom as tabs.
var form = Kob.form(root.querySelector('#ex-step-form'));

// A list of objects is more than data-options can express, so the room
// list is handed over from here.
Kob.combobox(root.querySelector('#ex-step-room'), {
  data: [
    { id: '104/5', text: '104/5 — Sukhumvit' },
    { id: '118/2', text: '118/2 — Ratchada' },
    { id: '122/1', text: '122/1 — Thonglor' }
  ]
});

var back = Kob.linkbutton(root.querySelector('#ex-step-back'));
var next = Kob.linkbutton(root.querySelector('#ex-step-next'));

var wizard = Kob.stepper(root.querySelector('#ex-stepper'), {
  onChange: function () { sync(); },
  onFinish: function () {
    Kob.toast({ msg: 'Lease created', type: 'success' });
    sync();
  }
});

function sync() {
  if (wizard.isFirst()) { back.disable(); } else { back.enable(); }
  next.setText(wizard.isLast() ? 'Create the lease' : 'Next');
  next.setIcon(wizard.isLast() ? 'icon-check-circle' : 'icon-forward');
}
sync();

root.querySelector('#ex-step-back').onclick = function () { wizard.prev(); };

root.querySelector('#ex-step-next').onclick = function () {
  // A wizard has to be sure of the step it is leaving. error() paints
  // the marker red and leaves it that way until the page clears it.
  if (wizard.getActive() === 0 && !form.validate()) { wizard.error(); return; }
  wizard.setStatus(wizard.getActive(), null);
  wizard.next();
};

root.querySelector('#ex-step-reset').onclick = function () {
  form.clear();
  wizard.reset();
  sync();
};
```

**Example — Stepper — down the side**

```html
<div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(250px,1fr));gap:26px">
  <div>
    <p class="kob-muted" style="margin:0 0 14px;font-size:13px">Progress, with a line of detail under each step.</p>
    <div class="kob-stepper" id="ex-vstep" data-options="direction:'vertical'"></div>
    <div style="display:flex;gap:8px;margin-top:18px">
      <a class="kob-linkbutton icon-arrow-up" id="ex-vstep-prev"><span class="kob-icon"></span>Back</a>
      <a class="kob-linkbutton kob-linkbutton-primary icon-arrow-down" id="ex-vstep-next"><span class="kob-icon"></span>Advance</a>
      <a class="kob-linkbutton icon-warn" id="ex-vstep-fail"><span class="kob-icon"></span>Fail this step</a>
    </div>
  </div>
  <div>
    <p class="kob-muted" style="margin:0 0 14px;font-size:13px">Small, dotted markers — a status rail rather than a wizard.</p>
    <div class="kob-stepper" id="ex-vstep2" data-options="direction:'vertical',size:'sm',markers:'dot',clickable:false"></div>
  </div>
</div>
```

```js
// With no titled children the widget is the indicator on its own, and
// the steps come from the option instead.
var track = Kob.stepper(root.querySelector('#ex-vstep'), {
  steps: [
    { title: 'Order placed',  text: 'Paid by card' },
    { title: 'Packed',        text: 'Warehouse 2' },
    { title: 'On the way',    text: 'Courier collected it' },
    { title: 'Delivered',     text: 'Signed for at reception' }
  ],
  active: 2,
  onChange: function (i, was, step) { Kob.toast(step.title); }
});

root.querySelector('#ex-vstep-prev').onclick = function () { track.prev(); };
root.querySelector('#ex-vstep-next').onclick = function () { track.next(); };
root.querySelector('#ex-vstep-fail').onclick = function () { track.error(); };

// Every step here carries its own status, so nothing is derived from
// where the active one sits.
Kob.stepper(root.querySelector('#ex-vstep2'), {
  steps: [
    { title: 'Meters read',    text: '84 of 84',   status: 'done' },
    { title: 'Invoices sent',  text: '84 of 84',   status: 'done' },
    { title: 'Payments in',    text: '56 of 84',   status: 'active' },
    { title: 'Reminders',      text: 'blocked by 3 disputes', status: 'error' },
    { title: 'Month locked',   text: 'due on the 5th' }
  ]
});
```

```html
<div class="kob-stepper">
  <div title="Tenant"  data-options="text:'Who is moving in'">…</div>
  <div title="Room"    data-options="text:'Which unit'">…</div>
  <div title="Confirm" data-options="iconCls:'icon-check-circle'">…</div>
</div>
```

```js
// Or as data, with no panels — a progress rail.
Kob.stepper('#delivery', {
  direction: 'vertical',
  steps: [
    { title: 'Packed',    text: 'Warehouse 2', status: 'done' },
    { title: 'On the way' },
    { title: 'Delivered' }
  ],
  active: 1
});
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| steps | array | `null` | Strings, or `{ title, text, iconCls, status }`. Left out, the titled children are read instead. |
| active | number | `0` | The step to start on. |
| direction | 'horizontal' \| 'vertical' | `'horizontal'` | Vertical puts the rail down the left and the panels beside it. |
| size | 'sm' \| 'md' | `'md'` | Marker diameter — 24px or 32px. |
| clickable | boolean | `true` | A click on a step moves to it. |
| linear | boolean | `true` | Only steps already reached can be clicked. `false` frees every step. |
| markers | 'number' \| 'dot' | `'number'` | What an unfinished marker shows. |
| doneIcon / errorIcon | string | `'icon-ok'` / `'icon-close'` |   |
| onChange | function(index, previous, step) | — | Any move, including `next()` and `prev()`. |
| onSelect | function(index, step) | — | A move the user clicked for. |
| onFinish | function() | — | Fires once, when `finish()` marks every step done. |

**Methods:** `go(i)`, `next()`, `prev()`, `finish()`, `reset()`, `canReach(i)`, `isFirst()`, `isLast()`, `isFinished()`, `getActive()`, `getStep(i?)`, `getSteps()`, `getPanel(i?)`, `setStatus(i, status)`, `error(i?)`, `setSteps(list)`.

### States

A step is `done`, `active` or `todo` according to where it sits relative to the current one. Pinning a `status` — on the step object or through `setStatus()` — overrides that, and is how a failed step stays red after the user has moved on:

```js
if (!form.validate()) { wizard.error(); return; }   // paint this step red
wizard.setStatus(wizard.getActive(), null);          // and clear it once fixed
wizard.next();
```

> `next()` on the last step calls `finish()` rather than doing nothing, so one button can carry a wizard from the first step to the end.

## dialog and modal

Built around an element that is already on the page: it keeps its content and becomes the window body, with the frame added around it.

**Example — Dialogs and windows**

```html
<div style="display:flex;flex-wrap:wrap;gap:8px">
  <a class="kob-linkbutton kob-linkbutton-primary icon-edit" id="ex-open-modal"><span class="kob-icon"></span>Modal dialog</a>
  <a class="kob-linkbutton icon-forward" id="ex-open-window"><span class="kob-icon"></span>Draggable window</a>
</div>

<div id="ex-modal" style="display:none">
  <form class="kob-form" id="ex-modal-form">
    <input class="kob-textbox" name="tenant" data-options="label:'Tenant',labelWidth:90,required:true">
    <input class="kob-numberbox" name="rent" data-options="label:'Rent',labelWidth:90,precision:2">
  </form>
</div>

<div id="ex-window" style="display:none">
  <p style="margin-top:0">Drag the header, pull any edge to resize, or use the corner buttons.</p>
  <div id="ex-window-grid" style="height:190px"></div>
</div>
```

```js
var form = Kob.form(root.querySelector('#ex-modal-form'));

var modal = Kob.dialog(root.querySelector('#ex-modal'), {
  title: 'Edit tenant',
  width: 420,
  buttons: [
    { text: 'Cancel', iconCls: 'icon-cancel', handler: function (d) { d.close(); } },
    { text: 'Save', iconCls: 'icon-save', primary: true, handler: function (d) {
        if (!form.validate()) { return; }
        Kob.toast({ msg: 'Saved ' + form.getValues().tenant, type: 'success' });
        d.close();
      } }
  ]
});

// modal:false turns the dialog into an application window: draggable,
// resizable, with minimise and maximise buttons.
var win = Kob.dialog(root.querySelector('#ex-window'), {
  title: 'Invoices', width: 560, height: 330, modal: false
});
Kob.datagrid(root.querySelector('#ex-window-grid'), {
  columns: [
    { field: 'room', title: 'Room', width: 90 },
    { field: 'tenant', title: 'Tenant', width: 150 },
    { field: 'rent', title: 'Rent', width: 110, align: 'right', formatter: KOB_FMT.money }
  ],
  data: KOB_SAMPLE.rows(30),
  pagination: false,
  filterable: false
});

root.querySelector('#ex-open-modal').onclick = function () { modal.open(); };
root.querySelector('#ex-open-window').onclick = function () { win.open(); };
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| title | string | `''` |   |
| width | number | `460` |   |
| height | number \| 'auto' | `'auto'` |   |
| modal | boolean | `true` | `false` makes it a draggable, resizable window. |
| closed | boolean | `true` | Start hidden; call `open()`. |
| buttons | array | `null` | `{ text, iconCls, primary, handler(dialog) }`. |
| draggable / resizable | boolean | `true` | Non-modal windows only. |
| minimizable / maximizable | boolean | `true` | Non-modal windows only. |
| sheet | boolean | `false` | Docks to the bottom edge — the shape phones expect. |
| minWidth / minHeight | number | `300` / `120` | Resize limits. |
| onOpen / onClose / onResize / onMove / onMinimize / onMaximize | function | — | `onMinimize` returning `false` keeps the window open. |

**Methods:** `open()`, `close()`, `isOpen()`, `setTitle(s)`, `setButtons(list)`, `maximize(on?)`, `restore()`, `minimize()`, `center()`, `resize({width,height})`, `move({left,top})`, `window()`, `getBody()`, `destroy()`.

### Two spellings

The `modal` flag decides everything, so it has a name at each end and you never have to remember which way round it goes:

```js
Kob.modal(el, { title: 'Edit' });        // dialog({ modal: true })
Kob.window(el, { title: 'Invoices' });   // dialog({ modal: false })
```

> Dialog markup is usually hidden with `style="display:none"` so it cannot flash before the widget is built. The widget clears that when it takes the element over — the frame owns visibility from then on.

## card

CSS only — there is no behaviour to attach, so there is no `Kob.card()`. Compose the parts you need.

```html
<div class="kob-card kob-card-hover">
  <div class="kob-card-header">
    <span class="kob-icon icon-home"></span>Sukhumvit
    <div class="kob-card-tools"><span class="kob-badge kob-badge-success">92%</span></div>
  </div>
  <img class="kob-card-media" src="…" alt="">
  <div class="kob-card-body">46 of 50 rooms occupied.</div>
  <div class="kob-card-footer">
    <span class="kob-muted kob-small">Updated today</span>
    <span class="kob-spacer"></span>
    <a class="kob-linkbutton icon-forward"><span class="kob-icon"></span>Open</a>
  </div>
</div>
```

| Class | Description |
| --- | --- |
| kob-card | The box. A flex column, so the body stretches. |
| kob-card-header | Title row. `kob-card-tools` inside pushes to the right. |
| kob-card-media | Full-bleed image at the top. |
| kob-card-body | Content. First and last child margins are collapsed away. |
| kob-card-footer | Action row on the accent tint. |
| kob-card-hover | Lifts on hover — for cards that are links. |

**Example — Cards, button groups and the layout helpers**

```html
<div class="kob-autogrid" style="--kob-min:230px">
  <div class="kob-card kob-card-hover">
    <div class="kob-card-header"><span class="kob-icon icon-home"></span>Sukhumvit
      <div class="kob-card-tools"><span class="kob-badge kob-badge-success">92%</span></div>
    </div>
    <div class="kob-card-body">
      <p class="kob-muted kob-small kob-m-0">46 of 50 rooms occupied.</p>
      <div class="kob-progressbar" data-options="value:92,height:8" style="margin-top:10px"></div>
    </div>
    <div class="kob-card-footer">
      <span class="kob-muted kob-small">Updated today</span>
      <span class="kob-spacer"></span>
      <a class="kob-linkbutton icon-forward"><span class="kob-icon"></span>Open</a>
    </div>
  </div>

  <div class="kob-card">
    <div class="kob-card-header"><span class="kob-icon icon-chart"></span>This month</div>
    <div class="kob-card-body">
      <div class="kob-flex kob-items-baseline kob-gap-2">
        <b style="font-size:28px">฿418,500</b><span class="kob-badge kob-badge-success">+4.2%</span>
      </div>
      <p class="kob-muted kob-small kob-mt-2 kob-mb-0">Collected rent across three buildings.</p>
    </div>
  </div>

  <div class="kob-card">
    <div class="kob-card-header"><span class="kob-icon icon-warn"></span>Needs attention</div>
    <div class="kob-card-body">
      <div class="kob-alert" data-options="type:'warn'" style="margin:0">7 invoices are overdue.</div>
    </div>
  </div>
</div>

<h4 style="margin:22px 0 8px;font-size:14px">Button groups</h4>
<div class="kob-flex kob-items-center kob-gap-3 kob-flex-wrap">
  <div class="kob-btn-group" id="ex-bg">
    <button class="kob-btn selected">Rows</button>
    <button class="kob-btn">Cards</button>
    <button class="kob-btn">Chart</button>
  </div>
  <div class="kob-btn-group">
    <a class="kob-linkbutton icon-chevron-left"><span class="kob-icon"></span></a>
    <a class="kob-linkbutton icon-chevron-right"><span class="kob-icon"></span></a>
  </div>
</div>

<h4 style="margin:22px 0 8px;font-size:14px">The 12-column row</h4>
<div class="kob-row">
  <div class="kob-col-8"><div class="kob-card"><div class="kob-card-body">kob-col-8</div></div></div>
  <div class="kob-col-4"><div class="kob-card"><div class="kob-card-body">kob-col-4</div></div></div>
  <div class="kob-col-6"><div class="kob-card"><div class="kob-card-body">kob-col-6</div></div></div>
  <div class="kob-col-3"><div class="kob-card"><div class="kob-card-body">kob-col-3</div></div></div>
  <div class="kob-col-3"><div class="kob-card"><div class="kob-card-body">kob-col-3</div></div></div>
</div>
```

```js
// A button group behaves as a segmented control when you keep the
// selected class on one member.
var group = root.querySelector('#ex-bg');
group.addEventListener('click', function (e) {
  var btn = e.target.closest('.kob-btn');
  if (!btn) { return; }
  group.querySelectorAll('.kob-btn').forEach(function (b) { b.classList.remove('selected'); });
  btn.classList.add('selected');
  Kob.toast('View: ' + btn.textContent);
});

// Cards, alerts and the progress bar above came from markup —
// Kob.parse() built them before this script ran.
```

## app shell

The bar across the top, the navigation down the side, and the scrolling area between them. CSS only — there is nothing to attach, because everything here is a class the page toggles for itself.

```html index.html
<div class="kob-appshell" id="shell">
  <header class="kob-appbar">
    <button class="kob-appbar-btn" id="rail"><span class="kob-icon icon-sidebar"></span></button>
    <span class="kob-appbar-brand"><span class="kob-appbar-mark">R</span>RentRoll</span>
    <span class="kob-spacer"></span>
    <button class="kob-appbar-user">
      <span class="kob-avatar">SP</span>
      <span class="kob-appbar-user-lines">
        <span class="kob-appbar-user-name">Somchai P.</span>
        <span class="kob-appbar-user-role">Administrator</span>
      </span>
    </button>
  </header>

  <nav class="kob-sidebar">
    <div class="kob-sidebar-title">Overview</div>
    <a class="kob-sidebar-item active" title="Dashboard">
      <span class="kob-icon icon-dashboard"></span>
      <span class="kob-sidebar-label">Dashboard</span>
    </a>
    <a class="kob-sidebar-item" title="Invoices">
      <span class="kob-icon icon-invoice"></span>
      <span class="kob-sidebar-label">Invoices</span>
      <span class="kob-badge kob-badge-danger">28</span>
    </a>
  </nav>

  <main class="kob-appmain">…</main>
  <div class="kob-statusbar kob-appfoot">…</div>
</div>
```

```js
// Collapsing the sidebar to an icon rail is one class on the shell.
rail.onclick = () => shell.classList.toggle('kob-sidebar-collapsed');
```

| Class | What it is |
| --- | --- |
| kob-appshell | The frame. A grid of bar / sidebar / content / footer; fills its parent, so give that a height. |
| kob-sidebar-collapsed | On the shell: narrows the sidebar to a rail and hides the labels. |
| kob-appbar | The top bar. `kob-spacer` and `kob-sep` work inside it. |
| kob-appbar-brand / -mark | Product name, and the square badge before it. |
| kob-appbar-btn | A quiet square button. A `kob-badge` inside it pins to the corner. |
| kob-appbar-user / -lines / -name / -role | The account block at the right-hand end. |
| kob-avatar | Initials or an `<img>`. `kob-avatar-sm`, `kob-avatar-lg`. |
| kob-sidebar | The navigation column. |
| kob-sidebar-title | A group heading inside it. |
| kob-sidebar-item | One entry: icon, `kob-sidebar-label`, optional badge. `active` marks the current page. |
| kob-sidebar-sep | A rule between groups. |
| kob-appmain | The scrolling content area. |
| kob-appfoot | Put it on a `kob-statusbar` to dock it under the content. |
| kob-pagehead / kob-crumbs | The heading row above the content, and the trail above that. |

The whole thing running, with a grid, tabs and a stepper inside it, is the [admin dashboard](https://kob-ui.com/examples.html#example-dashboard) on the examples page.

> Under 720px the sidebar becomes a rail on its own, whatever the page asked for — which is why every `kob-sidebar-item` should carry a `title`, so its name survives as a tooltip.

# Navigation

## menu

A list of commands in a floating panel: the dropdown behind a menu bar, the ribbon's split buttons, and any right-click menu.

> A menu is **not drawn where you build it**. Give it any element — a throwaway `document.createElement('div')` is fine — and place it with `showFor()` or `showAt()`.

**Example — Menus and context menus**

```html
<div style="display:flex;flex-wrap:wrap;gap:8px;align-items:center">
  <a class="kob-linkbutton icon-menu" id="ex-menu-open"><span class="kob-icon"></span>Open a menu</a>
  <span style="color:var(--kob-muted);font-size:13.5px">…or right-click the panel below</span>
</div>
<div id="ex-menu-zone" style="margin-top:12px;padding:26px;border:1px dashed var(--kob-border);border-radius:10px;text-align:center;color:var(--kob-muted)">
  right-click here
</div>
<p style="margin:10px 0 0;color:var(--kob-muted);font-size:13.5px" id="ex-menu-out"></p>
```

```js
var out = root.querySelector('#ex-menu-out');

// A menu lives on its own element and floats — nothing is drawn
// where you build it.
var m = Kob.menu(document.createElement('div'), {
  items: [
    { text: 'New',  iconCls: 'icon-add',  shortcut: 'Ctrl+N' },
    { text: 'Open', iconCls: 'icon-folder', shortcut: 'Ctrl+O' },
    { separator: true },
    { text: 'Export', iconCls: 'icon-download', items: [
      { text: 'CSV',   iconCls: 'icon-excel' },
      { text: 'PDF',   iconCls: 'icon-file' },
      { text: 'Print', iconCls: 'icon-print' }
    ] },
    { separator: true },
    { text: 'Delete', iconCls: 'icon-remove', disabled: true }
  ],
  onClick: function (item) { out.textContent = 'picked: ' + item.text; }
});

root.querySelector('#ex-menu-open').onclick = function () {
  m.showFor(this);
};

// One call turns any element into a right-click surface.
m.bindContextMenu(root.querySelector('#ex-menu-zone'));
```

### Item shape

| Key | Type | Description |
| --- | --- | --- |
| text | string | Caption. |
| iconCls | string | Icon at the left. |
| shortcut | string | Grey hint at the right, e.g. `'Ctrl+N'`. Display only. |
| items | MenuItem[] | Makes the entry a submenu. |
| separator | boolean | A rule instead of a command. |
| disabled / checked | boolean |   |
| onClick | function(item) | Per item. The menu's own `onClick` catches the rest. |

**Methods:** `showFor(anchor, { side, gap })`, `showAt(x, y)`, `bindContextMenu(element)`, `hide()`, `isOpen()`, `setItems(items)`, `panel()`.

## menubar

The File / Edit / View strip. Once a menu is open, moving along the bar switches menus without a second click — what desktop menus do.

**Example — Menu bar**

```html
<div class="kob-menubar" id="ex-menubar" style="border-radius:10px;border:1px solid var(--kob-border)"></div>
<p style="margin:10px 0 0;color:var(--kob-muted);font-size:13.5px" id="ex-mb-out">nothing chosen yet</p>
```

```js
var out = root.querySelector('#ex-mb-out');

Kob.menubar(root.querySelector('#ex-menubar'), {
  items: [
    { text: 'File', items: [
      { text: 'New tenant', iconCls: 'icon-add' },
      { text: 'Open',       iconCls: 'icon-folder' },
      { separator: true },
      { text: 'Print',      iconCls: 'icon-print', shortcut: 'Ctrl+P' }
    ] },
    { text: 'Edit', items: [
      { text: 'Undo', iconCls: 'icon-undo', shortcut: 'Ctrl+Z' },
      { text: 'Redo', iconCls: 'icon-redo', shortcut: 'Ctrl+Y' }
    ] },
    { text: 'View', items: [
      { text: 'Rows',    checked: true },
      { text: 'Cards' },
      { separator: true },
      { text: 'Refresh', iconCls: 'icon-reload' }
    ] },
    { text: 'Help', items: [{ text: 'About', iconCls: 'icon-tip' }] }
  ],
  // Once one menu is open, moving along the bar switches menus.
  onClick: function (item, top) {
    out.textContent = top.text + ' \u2192 ' + item.text;
  }
});
```

| Option | Type | Description |
| --- | --- | --- |
| items | array | `[{ text, iconCls, items: [...menu items] }]` |
| onClick | function(item, top) | Any command, with the top-level entry it came from. |

**Methods:** `openMenu(i)`, `closeMenu()`, `getMenu(i)`, `setItems(items)`.

## ribbon

Tabs of grouped commands. One large button, or a stack of small ones; a button with a `menu` opens it instead of firing.

**Example — Ribbon**

```html
<div class="kob-ribbon" id="ex-ribbon" style="border:1px solid var(--kob-border);border-radius:10px;overflow:hidden"></div>
<p style="margin:10px 0 0;color:var(--kob-muted);font-size:13.5px" id="ex-ribbon-out">click a command</p>
```

```js
var out = root.querySelector('#ex-ribbon-out');

Kob.ribbon(root.querySelector('#ex-ribbon'), {
  tabs: [
    { title: 'Home', groups: [
      { title: 'Records', items: [
        { text: 'New',    iconCls: 'icon-add' },
        { text: 'Edit',   iconCls: 'icon-edit', size: 'small' },
        { text: 'Delete', iconCls: 'icon-remove', size: 'small' },
        { text: 'Copy',   iconCls: 'icon-copy', size: 'small' }
      ] },
      { title: 'Data', items: [
        { text: 'Refresh', iconCls: 'icon-reload' },
        // A button with `menu` opens one instead of firing.
        { text: 'Export',  iconCls: 'icon-download', menu: [
          { text: 'CSV', iconCls: 'icon-excel' },
          { text: 'PDF', iconCls: 'icon-file' }
        ] }
      ] },
      { title: 'Report', items: [{ text: 'Print', iconCls: 'icon-print' }] }
    ] },
    { title: 'View', groups: [
      { title: 'Layout', items: [
        { text: 'Rows',  iconCls: 'icon-menu' },
        { text: 'Cards', iconCls: 'icon-folder' }
      ] }
    ] },
    { title: 'Help', groups: [
      { title: 'Support', items: [{ text: 'About', iconCls: 'icon-tip' }] }
    ] }
  ],
  // Clicking the tab that is already open folds the ribbon away.
  onClick: function (item) { out.textContent = 'command: ' + item.text; }
});
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| tabs | array | `null` | `[{ title, groups: [{ title, items: [...] }] }]` |
| selected | number | `0` | Tab shown first. |
| collapsible | boolean | `true` | Clicking the open tab folds the ribbon away. |
| collapsed | boolean | `false` | Start folded. |
| onSelect / onClick | function | — | `(index, tab)` / `(item)` |

**Item keys:** `text`, `iconCls`, `size: 'large' | 'small'`, `disabled`, `menu`, `onClick`. Consecutive small buttons stack three to a column.

**Methods:** `select(i)`, `collapse()`, `expand()`, `toggleCollapse()`, `setTabs(tabs)`.

## tree

Nodes are plain objects. Children may be an array, or left out with `state: 'closed'` to be fetched the first time the node opens.

**Example — Tree**

```html
<div style="display:grid;grid-template-columns:minmax(0,1fr) minmax(0,1fr);gap:16px">
  <div>
    <div class="kob-tree" id="ex-tree" style="height:250px;border:1px solid var(--kob-border);border-radius:10px;padding:8px"></div>
    <div style="display:flex;gap:6px;margin-top:10px;flex-wrap:wrap">
      <a class="kob-linkbutton icon-chevron-down" id="ex-tree-all"><span class="kob-icon"></span>Expand all</a>
      <a class="kob-linkbutton icon-chevron-up" id="ex-tree-none"><span class="kob-icon"></span>Collapse all</a>
    </div>
  </div>
  <div>
    <div class="kob-tree" id="ex-tree-check" style="height:250px;border:1px solid var(--kob-border);border-radius:10px;padding:8px"></div>
    <p style="margin:10px 0 0;color:var(--kob-muted);font-size:13.5px" id="ex-tree-out">nothing ticked</p>
  </div>
</div>
```

```js
var data = [
  { id: 1, text: 'Sukhumvit', iconCls: 'icon-home', children: [
    { id: 11, text: 'Floor 1', children: [
      { id: 111, text: 'Room 101/2' },
      { id: 112, text: 'Room 102/3' }
    ] },
    { id: 12, text: 'Floor 2', children: [{ id: 121, text: 'Room 201/1' }] }
  ] },
  { id: 2, text: 'Ratchada', iconCls: 'icon-home', children: [
    { id: 21, text: 'Floor 1', children: [{ id: 211, text: 'Room 101/5' }] }
  ] }
];

var t = Kob.tree(root.querySelector('#ex-tree'), {
  data: JSON.parse(JSON.stringify(data)),
  lines: true,
  onSelect: function (node) { Kob.toast(node.text); }
});
root.querySelector('#ex-tree-all').onclick = function () { t.expandAll(); };
root.querySelector('#ex-tree-none').onclick = function () { t.collapseAll(); };

// With checkbox:true a folder ticks and unticks its children, and
// shows a dash while only some of them are ticked.
var out = root.querySelector('#ex-tree-out');
Kob.tree(root.querySelector('#ex-tree-check'), {
  data: JSON.parse(JSON.stringify(data)),
  checkbox: true,
  expandDepth: 2,
  onCheck: function () {
    var picked = Kob.instance(root.querySelector('#ex-tree-check'), 'tree').getChecked();
    out.textContent = picked.length
      ? picked.length + ' ticked: ' + picked.map(function (n) { return n.text; }).join(', ')
      : 'nothing ticked';
  }
});
```

### Node shape

```js
{
  id: 1,
  text: 'Sukhumvit',
  iconCls: 'icon-home',
  state: 'open',            // or 'closed'
  checked: false,
  children: [ /* … */ ]     // omit + state:'closed' to load lazily from `url`
}
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| data | TreeNode[] | `null` | The root nodes. |
| url | string | `''` | Root through `Kob.config.request`; lazy children are fetched from the same URL with `id`. |
| idField / textField / childrenField | string | `id` / `text` / `children` | Read your own shape without remapping. |
| checkbox | boolean | `false` | A tick box on every node. |
| cascadeCheck | boolean | `true` | Folders tick their children; partly-ticked folders show a dash. |
| lines | boolean | `false` | Guide lines down each branch. |
| expandDepth | number | `1` | How deep to start open. |
| formatter | function(node) | — | HTML for one label. |
| onSelect / onClick / onDblClick | function(node) | — |   |
| onExpand / onCollapse | function(node) | — |   |
| onCheck | function(node, checked) | — |   |
| onContextMenu | function(event, node) | — | Pairs with `menu.showAt()`. |

**Methods:** `loadData`, `reload`, `expand(node)`, `collapse(node)`, `toggle(node)`, `expandAll()`, `collapseAll()`, `select(node)`, `getSelected()`, `find(id)`, `check(node, on)`, `getChecked()`, `walk(nodes, fn)`, `getData()`.

## desktop

A windowed shell: wallpaper with launcher icons, a taskbar, a start menu, and one window per running app. Each window is a non-modal [dialog](https://kob-ui.com/docs.html#dialog), so dragging, resizing and maximising come from that widget — what the desktop adds is knowing what is running, which window has focus, and how to get a minimised one back.

**Example — Desktop shell**

```html
<div class="kob-desktop" id="ex-desktop" style="height:520px;border:1px solid var(--kob-border);border-radius:12px;overflow:hidden"></div>
<p style="margin:10px 0 0;color:var(--kob-muted);font-size:13.5px">
  Double-click an icon, or use Start. Windows drag, resize, minimise to the taskbar and maximise.
</p>
```

```js
var money = KOB_FMT.money;

Kob.desktop(root.querySelector('#ex-desktop'), {
  user: { name: 'kob', onLogout: function () { Kob.toast('Logged out'); } },
  startExtras: [
    { text: 'Settings', iconCls: 'icon-settings' },
    { text: 'Log out',  iconCls: 'icon-back' }
  ],
  apps: [
    {
      id: 'rooms', title: 'Rooms', iconCls: 'icon-home', width: 640, height: 380,
      // Build the window contents yourself when it opens.
      onOpen: function (win, body) {
        var grid = document.createElement('div');
        grid.style.height = '100%';
        body.appendChild(grid);
        Kob.datagrid(grid, {
          columns: [
            { field: 'room',   title: 'Room',   width: 90 },
            { field: 'tenant', title: 'Tenant', width: 160 },
            { field: 'rent',   title: 'Rent',   width: 110, align: 'right', formatter: money }
          ],
          data: KOB_SAMPLE.rows(40),
          fit: true,
          filterable: false,
          pageSize: 20
        });
      }
    },
    {
      id: 'invoices', title: 'Invoices', iconCls: 'icon-file', width: 520, height: 320,
      content: '<div style="padding:18px"><h3 style="margin-top:0">Invoices</h3>' +
        '<p>Any HTML works as a window body. Widgets in it are parsed.</p>' +
        '<div class="kob-progressbar" data-options="value:64"></div></div>'
    },
    {
      id: 'chart', title: 'Reports', iconCls: 'icon-chart', width: 420, height: 260,
      content: '<div style="padding:18px"><div class="kob-alert" data-options="type:&#39;info&#39;">' +
        'Reports would render here.</div></div>'
    },
    { id: 'settings', title: 'Settings', iconCls: 'icon-settings', width: 380, height: 220,
      content: '<div style="padding:18px">Settings</div>' }
  ]
});
```

### Apps

An app says what its window contains, in one of three ways.

| Key | Type | Description |
| --- | --- | --- |
| id | string | Required. What `open()` and `close()` take. |
| title | string | Window title, icon caption and taskbar label. |
| iconCls | string | Icon from the built-in set. |
| icon | string | An image URL instead, for a real app icon. |
| content | string | HTML for the window body. Widgets in it are parsed. |
| href | string | Fetch a fragment into the body instead. |
| onOpen | function(win, body) | Or build the contents yourself. |
| width / height | number | Window size. |
| single | boolean | Default true — opening again focuses the existing window. |
| hidden | boolean | Reachable through `open()`, but not shown as an icon. |

### Options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| apps | App[] | `null` | As above. |
| icons | boolean | `true` | Launcher icons on the wallpaper. |
| taskbar | boolean | `true` | The bar along the bottom. |
| startLabel | string \| false | `'Start'` | Start button text; `false` hides it. |
| startExtras | MenuItem[] | — | Entries under the app list. |
| clock | boolean | `true` | Clock at the right. |
| user | object | — | `{ name, iconCls, onLogout }` |
| wallpaper | string | — | Any CSS background. |
| onOpen / onClose / onFocus | function(app, win) | — |   |

**Methods:** `open(id)` returns the window's Dialog, plus `close(id)`, `closeAll()`, `minimize(id)`, `getRunning()`, `getWindow(id)`, `setApps(apps)`, `setWallpaper(css)`.

> The desktop fills its parent, so give that parent a height. On a full page that means `html, body { height: 100% }`.

# Data

## datagrid

The whole result set lives in memory, and searching, filtering, sorting and paging all happen locally — so changing a filter never costs another round trip.

**Example — A grid in eight lines**

```html
<div class="ex-grid" style="height:330px"></div>
```

```js
Kob.datagrid(root.querySelector('.ex-grid'), {
  columns: [
    { field: 'room',     title: 'Room',     width: 90 },
    { field: 'tenant',   title: 'Tenant',   width: 160 },
    { field: 'building', title: 'Building', width: 130 },
    { field: 'rent',     title: 'Rent',     width: 110, align: 'right' }
  ],
  data: KOB_SAMPLE.rows(48)
});
```

### Options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| columns | array | `null` | See [Column definition](https://kob-ui.com/docs.html#datagrid-columns). A nested `[[…]]` array is accepted for EasyUI-shaped configs. |
| data | array \| object | `null` | Rows, `{ rows }` or `{ data }`. |
| url | string | `''` | Fetched through `Kob.config.request`. |
| queryParams | object | `null` | Sent with the request. |
| loadFilter | function(payload) | — | Reshape the payload before it is read. |
| idField | string | `''` | The column that identifies a row, for matching one back after an edit. |
| pagination | boolean | `true` | The footer with page controls. `false` renders every row that survives the filters. |
| pageSize | number | `50` |   |
| pageList | number[] | `[20,50,100]` | Choices in the rows-per-page menu. |
| searchable | boolean | `true` | The free-text box in the footer. Needs `pagination`, which is what draws the footer. |
| filterable | boolean | `true` | The chip row above the header. |
| rownumbers | boolean | `false` | A leading column counting the rows. Dropped on a single-column grid, where it would be the only thing beside the content. |
| showHeader | boolean | `true` | `false` hides the header row — and with it sorting, resizing and the chips. |
| striped | boolean | `true` |   |
| singleSelect | boolean | `true` | `false` lets clicks accumulate a selection. See [Selecting rows](https://kob-ui.com/docs.html#datagrid-selection). |
| checkbox | boolean | `false` | A leading column of checkboxes, with a tri-state box in the header. Turns multi-select on by itself unless `singleSelect` was set. |
| selectOnCheckbox | boolean | `false` | Only the checkbox changes the selection; clicking the row leaves it alone. |
| resizable | boolean | `true` | Drag the right edge of a header cell to resize that column. `resizable: false` on a column pins that one. |
| minColWidth | number | `48` | A column will not be dragged narrower than this. |
| fit | boolean | `false` | Fill the parent's height. |
| emptyMsg | string | locale | Shown when nothing matches. |
| rowActions | array | `null` | Buttons over the row instead of in a column — see [Editing from the row](https://kob-ui.com/docs.html#datagrid-rowactions). |
| rowActionsOn | 'hover' \| 'selected' | `'hover'` | `'selected'` drops the hover behaviour and shows the strip only on the selected row. |

### Column definition

| Key | Type | Description |
| --- | --- | --- |
| field | string | Property on the row. A column without one is decoration: it cannot sort, filter or be searched. |
| title | string | Header text. |
| width | number | Pixels, and a starting point — columns that fit are stretched to fill the grid. |
| align | 'left' \| 'center' \| 'right' | Applied to the header cell and every body cell. |
| sortable | boolean | `false` makes the header inert. |
| resizable | boolean | `false` drops this column's grip while the rest stay draggable. |
| formatter | function(value, row, index) | Returns the cell's HTML. Filtering, searching and the chip menus all read what it produced. |
| editor | string \| object | `'text'`, `'numberbox'`, or `{ type, options: { precision } }`. A column without one is not editable. |
| filter | false \| string | `false` drops the chip; a string forces its kind: `text`, `number`, `enum`, `bool`. |

### Methods

| Method | Returns | Description |
| --- | --- | --- |
| loadData(rows) | this | Replace the rows. Accepts an array, `{ rows }` or `{ data }`. Clears the selection with them — they are new objects. |
| reload(url?) | Promise | Fetch again. Accepts `{ url, queryParams }`. |
| getRows() / getData() | Row[] | Everything loaded. Two spellings of the same list. |
| getVisibleRows() | Row[] | After the search box, the chips and the sort — every page of it, not the one on screen. |
| getRowByIndex(i) | Row | By position in the loaded set. |
| getSelected() | Row \| null | The last row selected. |
| getSelections() | Row[] | Every selected row — including ones the current page is not showing. |
| getSelectionCount() | number |   |
| isSelected(row) | boolean | Takes the row itself, not an index. |
| selectRow(i) / unselectRow(i) | this |   |
| selectAll() / unselectAll() | this | Every row the filters let through, not only the page on screen. |
| clearSelections() | this | The older name for `unselectAll()`. |
| sort(field, order?) | this | Omit the order to flip it. |
| setFilter(field, value) | this | `{ in: [...] }`, `{ ge: n }`, `{ q: 'text' }`, `{ eq: v }`, or `null` to drop it. |
| getFilters() / clearFilters() | object / this |   |
| search(text) | this | As if typed into the footer box, which it also fills in. |
| gotoPage(n) / pageCount() | this / number | Clamped to what exists. |
| beginEdit(i) / endEdit(i) / cancelEdit() | this | See [Inline editing](https://kob-ui.com/docs.html#datagrid-editing). |
| refreshRow(i) | this | Redraw after changing a row's data behind the grid's back. |
| rowElement(i) | HTMLElement \| null | The `<tr>`, if that row is on the page being shown. |
| loading() / loaded() | this | Show or hide the mask by hand. |
| resize() | this | Re-measure columns. Rarely needed — it watches its own box. |
| refresh() | void | Rebuild after options changed through `option({ … })`. |
| destroy() | void | Give the element back as it was found. |

### Events

| Event | Arguments |
| --- | --- |
| onClickRow / onDblClickRow / onSelect / onUnselect | `(index, row)` |
| onSelectionChange | `(rows)` — every row now selected, however the change was made |
| onResizeColumn | `(field, width)` — when a drag finishes |
| onLoadSuccess / onLoadError | `(data)` / `(error)` |
| onSortChange | `(field, order)` |
| onFilterChange | `(filters)` |
| onEndEdit | `(index, row)` — the row after the editors were written back |

### Columns, and the widths they end up with

A `width` is a starting point rather than a contract. While the widths add up to less than the grid is wide, every column is stretched in proportion so the table fills its box — which is why a three-column grid never leaves a strip of empty background down the right. When they add up to more, the body scrolls sideways and the header follows it.

Drag one and that stops. A width set by hand is a decision, so the proportional stretch is switched off for good and only the last column — the one with no grip, because there is nothing to its right to give width back to — takes up the slack. The new width is written onto the column definition, so it survives sorting, paging and a reload, and `onResizeColumn` is where you would write it somewhere more permanent.

**Example — Widths, alignment, and the columns that opt out**

```html
<p class="kob-muted" style="margin:0 0 10px;font-size:13.5px">
  Drag the edge of a header cell. <b>Room</b> is pinned and has no grip;
  <b>Note</b> never sorts and offers no filter chip.
</p>
<div class="ex-grid" style="height:460px"></div>
<p id="dc-log" class="kob-muted" style="margin:10px 0 0;font-size:12.5px"></p>
```

```js
// Widths are a starting point, not a contract: while they add up to
// less than the grid is wide, every column is stretched in proportion
// so the table fills its box. Drag one and that stops — a width set by
// hand is a decision, and from then on only the last column, the one
// with no grip, takes up the slack.
var grid = Kob.datagrid(root.querySelector('.ex-grid'), {
  columns: [
    // No grip on this one, whatever the others do.
    { field: 'room',     title: 'Room',     width: 80,  resizable: false },
    { field: 'tenant',   title: 'Tenant',   width: 160 },
    { field: 'building', title: 'Building', width: 120 },
    // Right-aligned numbers, formatted for reading. Filtering and
    // sorting still see the number underneath.
    { field: 'rent',     title: 'Rent',     width: 110, align: 'right',
      formatter: KOB_FMT.money },
    { field: 'due',      title: 'Due',      width: 110, align: 'center' },
    // Free text, all of it different: sorting it means nothing and a
    // pick-list of 60 values helps nobody, so both are turned off.
    { field: 'note',     title: 'Note',     width: 200,
      sortable: false, filter: false }
  ],
  data: KOB_SAMPLE.rows(60).map(function (r) {
    r.note = 'Contract ends ' + r.due + ' · unit ' + r.room;
    return r;
  }),
  pageSize: 8,
  // Nothing may be dragged narrower than this.
  minColWidth: 60,

  // Fires when a drag finishes. Widths live on the column objects, so
  // this is also where you would remember them.
  onResizeColumn: function (field, width) {
    root.querySelector('#dc-log').textContent = field + ' is now ' + width + 'px';
    // localStorage.setItem('grid.' + field, width);
  }
});

// Restoring them next time is the mirror image — read the widths back
// into the column definitions before the grid is built:
//
//   columns.forEach(function (c) {
//     var saved = localStorage.getItem('grid.' + c.field);
//     if (saved) { c.width = Number(saved); }
//   });
void grid;
```

### Filter chips

Above the header sits one chip per column. Each decides what to offer by looking at the data: a pick-list for categories, a lower bound for numbers, a contains box for free text.

**They filter what the reader sees.** A column with a formatter is flattened to text once per row and cached, so a status column rendering `1` as a green "Paid" badge filters and searches as *Paid*.

#### How a chip decides what kind it is

| What the column holds | Chip | What it offers |
| --- | --- | --- |
| Only booleans | `bool` | A pick-list of the two rendered labels — *Yes* and *No*, or whatever the formatter made of them. |
| Only numbers, all of them 0 or 1 | `enum` | A pick-list. A flag stored as a number is still a flag. |
| Only numbers | `number` | A lower bound: *at least* n. |
| Text, few distinct values | `enum` | A pick-list. "Few" means no more than a dozen, and no more than a third of the rows — a column of unique names is not a category. |
| Anything else | `text` | A contains box. |

`filter: 'number'` on the column overrides the guess, `filter: false` drops that chip, and `filterable: false` on the grid drops the row. It also hides itself when there is nothing to choose between — fewer than two filterable columns, or a grid with no header.

**Example — Filters read what the reader sees**

```html
<div class="ex-grid" style="height:360px"></div>
<div style="display:flex;flex-wrap:wrap;gap:8px;margin-top:10px">
  <a class="kob-linkbutton icon-filter" id="ex-f-overdue"><span class="kob-icon"></span>Only overdue</a>
  <a class="kob-linkbutton icon-sum" id="ex-f-big"><span class="kob-icon"></span>Rent ≥ 8,000</a>
  <a class="kob-linkbutton icon-cancel" id="ex-f-clear"><span class="kob-icon"></span>Clear</a>
</div>
```

```js
var grid = Kob.datagrid(root.querySelector('.ex-grid'), {
  columns: [
    { field: 'room',     title: 'Room',     width: 90 },
    { field: 'tenant',   title: 'Tenant',   width: 150 },
    { field: 'building', title: 'Building', width: 120 },
    { field: 'rent',     title: 'Rent',     width: 110, align: 'right',
      formatter: KOB_FMT.money },
    { field: 'due',      title: 'Due',      width: 110 },
    // The cell renders a badge; the chip menu still offers
    // paid / pending / overdue, because filtering runs on the
    // text the formatter produced.
    { field: 'status',   title: 'Status',   width: 110,
      formatter: function (v) {
        return KOB_FMT.badge(v, v === 'paid' ? 'success'
          : v === 'overdue' ? 'danger' : 'warn');
      } },
    // 1 and 0 read as Yes and No, and filter that way too.
    { field: 'active',   title: 'Active',   width: 90, align: 'center',
      formatter: function (v) {
        return KOB_FMT.badge(v ? 'Yes' : 'No', v ? 'info' : 'muted');
      } }
  ],
  data: KOB_SAMPLE.rows(137),
  rownumbers: true,
  pageSize: 20
});

// The same filters the chips set, driven from your own toolbar.
root.querySelector('#ex-f-overdue').onclick = function () {
  grid.setFilter('status', { in: ['overdue'] });
};
root.querySelector('#ex-f-big').onclick = function () {
  grid.setFilter('rent', { ge: 8000 });
};
root.querySelector('#ex-f-clear').onclick = function () {
  grid.clearFilters();
};
```

### Searching and sorting

The box in the footer matches every column that has a `field`, against the same flattened text the chips use — so a search for *overdue* finds the rows whose status badge reads Overdue, and a formatted `12,500.00` is found by typing `12,5`. `search(text)` does the same from code, and fills the box in so the user can see what they are looking at.

Sorting compares numbers as numbers and everything else with `localeCompare`, which is what puts *Ähnlich* where a reader expects it rather than after *Z*. Null and undefined sort as an empty string. Unlike filtering, sorting reads the underlying value, not the formatter's output: a date rendered as *5 Jan 2026* still sorts by the ISO string behind it.

### Selecting rows

One row at a time by default. `checkbox: true` or `singleSelect: false` turns multi-select on, and from there the gestures are the ones the desktop taught everyone:

| Gesture | What it does |
| --- | --- |
| Click | Toggles that row. |
| Ctrl / Cmd + click | Toggles it explicitly, leaving the rest alone. |
| Shift + click | Takes the run from the last row touched to this one, walking the rows *in the order they are on screen* — sorted and filtered — because that is the run being pointed at. |
| The row's checkbox | Changes the selection and nothing else: no row click, no editor, no dialog opening behind the tick. |
| The header checkbox | Ticks or clears the page in front of the user, and shows a tri-state mark when part of it is selected. It reports on that page only — it cannot honestly claim to have ticked rows nobody has looked at. |

The selection is kept as rows rather than as classes on whichever `<tr>`s exist at the moment, so it survives paging, sorting and filtering: rows picked on page one are still picked on page two, and `getSelections()` returns all of them. `selectAll()` means every row the filters let through, not the page on screen. `loadData()` clears it, because those rows are new objects.

**Example — Picking rows: checkboxes, Ctrl, Shift — and draggable columns**

```html
<p class="kob-muted" style="margin:0 0 10px;font-size:13.5px">
  Click a row, or its checkbox. <b>Ctrl</b> (<b>Cmd</b>) adds one, <b>Shift</b> takes the
  run from the last row you touched, and the box in the header ticks the whole page.
  Drag the edge of any header cell to resize that column.
</p>
<div class="kob-toolbar" style="border:1px solid var(--kob-border);border-bottom:none;border-radius:var(--kob-radius) var(--kob-radius) 0 0">
  <a class="kob-linkbutton icon-ok" id="ds-all"><span class="kob-icon"></span>Select all</a>
  <a class="kob-linkbutton icon-close" id="ds-none"><span class="kob-icon"></span>Clear</a>
  <span class="kob-sep"></span>
  <a class="kob-linkbutton kob-linkbutton-danger kob-linkbutton-soft icon-remove" id="ds-del"><span class="kob-icon"></span>Delete selected</a>
  <span class="kob-spacer"></span>
  <span id="ds-count" class="kob-muted" style="font-size:12.5px"></span>
</div>
<div id="ds-grid" style="height:330px"></div>
```

```js
var rows = KOB_SAMPLE.rows(60);

// checkbox:true turns multi-select on by itself — a column of
// checkboxes that only ever holds one tick is a radio button in the
// wrong clothes.
var grid = Kob.datagrid(root.querySelector('#ds-grid'), {
  columns: [
    { field: 'room',     title: 'Room',     width: 90 },
    { field: 'tenant',   title: 'Tenant',   width: 170 },
    { field: 'building', title: 'Building', width: 130 },
    { field: 'rent',     title: 'Rent',     width: 110, align: 'right', formatter: KOB_FMT.money },
    { field: 'status',   title: 'Status',   width: 110, resizable: false, formatter: function (v) {
        return KOB_FMT.badge(v, v === 'paid' ? 'success' : v === 'overdue' ? 'danger' : 'warn');
      } }
  ],
  data: rows,
  checkbox: true,
  pageSize: 8,
  filterable: false,
  fit: true,

  // One event for every way the selection can change — a click, a
  // checkbox, Shift over a run, or the header box.
  onSelectionChange: function (picked) { show(picked); }
});

var out = root.querySelector('#ds-count');

function show(picked) {
  if (!picked.length) { out.textContent = 'Nothing selected'; return; }
  var total = picked.reduce(function (n, r) { return n + r.rent; }, 0);
  out.innerHTML = '<b>' + picked.length + '</b> selected · ' + KOB_FMT.money(total);
}
show([]);

// The selection is kept as rows, not as highlighted <tr>s — so it
// survives paging, sorting and filtering, and selectAll() means every
// row the filters let through, not just the eight on screen.
root.querySelector('#ds-all').onclick = function () { grid.selectAll(); };
root.querySelector('#ds-none').onclick = function () { grid.unselectAll(); };

root.querySelector('#ds-del').onclick = function () {
  var picked = grid.getSelections();
  if (!picked.length) { return Kob.alert({ title: 'Nothing selected', msg: 'Tick a row first.' }); }
  Kob.confirm({ title: 'Delete', msg: 'Remove ' + picked.length + ' room(s)?' }).then(function (yes) {
    if (!yes) { return; }
    rows = rows.filter(function (r) { return picked.indexOf(r) === -1; });
    grid.loadData(rows);
    show([]);
    Kob.toast({ msg: 'Deleted ' + picked.length, type: 'warn' });
  });
};
```

### Loading from a server

`url` fetches once, through `Kob.config.request`, and everything after that is local. There is no server-side paging protocol to implement: the grid asks for the result set, then does the searching, filtering, sorting and paging itself. A `{ rows, total }` envelope is understood, as is a bare array or `{ data }`; anything else is what `loadFilter` is for.

When the request fails the grid empties itself rather than leaving stale rows under a failed refresh, calls `Kob.config.onRequestError`, and then fires `onLoadError`. `reload()` refetches the same URL; `reload('/api/other')` or `reload({ url, queryParams })` changes it and remembers the change.

**Example — Loading from an API**

```html
<div class="ex-grid" style="height:280px"></div>
```

```js
// Kob.config.request is the single place the library talks to a
// server. Replace it once and every widget follows — headers, an
// envelope to unwrap, a redirect on 401.
//
// Kob.config.request = function (url, params) {
//   return fetch(url + new URLSearchParams(params || {}), {
//     headers: { Authorization: 'Bearer ' + token }
//   }).then(function (res) {
//     if (res.status === 401) { location.href = '/login'; return []; }
//     return res.json();
//   }).then(function (payload) {
//     if (!payload.success) { throw new Error(payload.message); }
//     return payload.data;          // an array, or { rows, total }
//   });
// };

// Stubbed here so the page needs no backend of its own.
Kob.config.request = function () {
  return new Promise(function (resolve) {
    setTimeout(function () { resolve({ rows: KOB_SAMPLE.rows(60) }); }, 700);
  });
};

Kob.datagrid(root.querySelector('.ex-grid'), {
  columns: [
    { field: 'room',   title: 'Room',   width: 90 },
    { field: 'tenant', title: 'Tenant', width: 170 },
    { field: 'rent',   title: 'Rent',   width: 110, align: 'right', formatter: KOB_FMT.money }
  ],
  url: '/api/invoices',
  queryParams: { year: 2026 },
  pageSize: 20,
  onLoadSuccess: function () { Kob.toast({ msg: 'Loaded', type: 'info' }); }
});
```

### Inline editing

`beginEdit(i)` turns the cells of that row into inputs — but only the columns that declared an `editor`; the rest stay as they are, which is how a key or a computed total is kept out of reach. A `numberbox` editor reads back as a number, rounded to its `precision`; a `text` one as a string.

`endEdit(i)` writes the inputs back into the row, redraws it and fires `onEndEdit` — which is where the save request belongs. `cancelEdit()` drops them without writing. Committing on Enter and abandoning on Escape is two lines in the page, not a built-in, because which key means "save" is an application's decision and not a widget's.

**Example — Editing a row in place**

```html
<div class="ex-grid" style="height:300px"></div>
<p style="margin:10px 0 0;color:var(--kob-muted);font-size:13.5px">Double-click a row to edit it, then press Enter or use Save.</p>
```

```js
var editing = -1;

var grid = Kob.datagrid(root.querySelector('.ex-grid'), {
  columns: [
    { field: 'room',   title: 'Room',   width: 90 },
    { field: 'tenant', title: 'Tenant', width: 160, editor: 'text' },
    { field: 'rent',   title: 'Rent',   width: 120, align: 'right',
      formatter: KOB_FMT.money,
      editor: { type: 'numberbox', options: { precision: 2 } } }
  ],
  data: KOB_SAMPLE.rows(12),
  pagination: false,
  onDblClickRow: function (index) {
    if (editing >= 0) { grid.endEdit(editing); }
    editing = index;
    grid.beginEdit(index);
  },
  onEndEdit: function (index, row) {
    editing = -1;
    Kob.toast({ msg: 'Saved ' + row.room + ' — ' + KOB_FMT.money(row.rent), type: 'success' });
  }
});

root.addEventListener('keydown', function (e) {
  if (e.key === 'Enter' && editing >= 0) { grid.endEdit(editing); }
  if (e.key === 'Escape' && editing >= 0) { grid.cancelEdit(); editing = -1; }
});
```

### Editing and deleting from the row

Not every table has room for a column of buttons. `rowActions` gives you the actions without one: a strip that appears over a row when the pointer is on it, and parks on the row the user clicked so it stays reachable from the keyboard.

```js
Kob.datagrid('#grid', {
  columns: [ … ],
  data: rows,

  rowActions: [
    { text: 'Edit', iconCls: 'icon-edit', handler: edit },
    {
      text: 'Delete', iconCls: 'icon-remove', color: 'danger',
      disabled: function (row) { return row.status === 'paid'; },
      handler: remove
    }
  ],

  // The other half of the same idea — most people try this first.
  onDblClickRow: function (i, row) { edit(row); }
});
```

| Key | Type | What it does |
| --- | --- | --- |
| text | string | Button caption. Leave it out for an icon-only button; the label then comes from `title`. |
| iconCls | string | e.g. `'icon-remove'`. |
| color | string | One of the five button colours. |
| soft | boolean | Defaults to `true` — a strip of solid buttons over a row is too loud. |
| disabled | boolean \| function | `(row, index)`. Re-evaluated for every row the strip lands on. |
| handler | function | `(row, index)`, with the grid element as `this`. |

There is one strip, moved to whichever row wants it, rather than a copy per row: a grid repages and re-sorts constantly, and forty copies of the same three buttons is forty times the DOM for something only ever seen once. It hides itself when the row it belongs to scrolls out of the body's own viewport, so the buttons never end up floating over the header or the pager.

`rowActionsOn: 'selected'` drops the hover behaviour and shows the strip only on the selected row. Methods `showRowActions(tr, hovering)` and `hideRowActions()` drive it by hand.

> The strip covers the right-hand end of the row while it is open, so put the column you can least afford to hide on the left. That is the trade for not spending a column on buttons — one or the other has to give.

**Example — Edit and delete from the row itself**

```html
<p class="kob-muted" style="margin:0 0 10px;font-size:13.5px">
  No actions column. Move the pointer over a row — or click one and use the keyboard.
  Double-clicking a row edits it too.
</p>
<div id="re-grid" style="height:280px"></div>
<p class="kob-muted" style="margin:10px 0 0;font-size:13.5px" id="re-out">nothing yet</p>
```

```js
var rows = KOB_SAMPLE.rows(40);
var out = root.querySelector('#re-out');

function edit(row) {
  Kob.prompt({ title: 'Rent for ' + row.room, msg: 'New amount', value: row.rent })
    .then(function (value) {
      if (value === null) { return; }
      row.rent = Number(value) || row.rent;
      grid.loadData(rows);
      out.textContent = row.room + ' set to ' + KOB_FMT.money(row.rent);
    });
}

function remove(row) {
  Kob.sweet({
    type: 'question',
    title: 'Delete ' + row.room + '?',
    msg: row.tenant + ' would lose the room.',
    showCancel: true, confirmText: 'Delete', danger: true
  }).then(function (yes) {
    if (!yes) { return; }
    rows.splice(rows.indexOf(row), 1);
    grid.loadData(rows);
    out.textContent = row.room + ' deleted';
  });
}

var grid = Kob.datagrid(root.querySelector('#re-grid'), {
  columns: [
    { field: 'room',     title: 'Room',     width: 90 },
    { field: 'tenant',   title: 'Tenant',   width: 150 },
    { field: 'building', title: 'Building', width: 130 },
    { field: 'rent',     title: 'Rent',     width: 110, align: 'right', formatter: KOB_FMT.money }
  ],
  data: rows,
  filterable: false,
  pageSize: 20,

  // One strip, moved to whichever row wants it. Nothing is added to the
  // columns, so the table is as wide as its data and no wider.
  rowActions: [
    { text: 'Edit', iconCls: 'icon-edit', handler: edit },
    {
      text: 'Delete', iconCls: 'icon-remove', color: 'danger',
      // A paid room is not deletable — the button says so rather than
      // letting the click through and failing afterwards.
      disabled: function (row) { return row.status === 'paid'; },
      handler: remove
    }
  ],

  onDblClickRow: function (i, row) { edit(row); }
});
```

### One column, and it stops looking like a table

A grid of one column has nothing to sort against another, nothing to resize, and no second column to filter by — so it drops the header furniture and the chip row rather than showing controls that lead nowhere. What is left is a paged, searchable list whose rows look like whatever the formatter returns. `showHeader: false` does the same to a grid of many columns.

It is the same widget, so the search box, the pager, the row events, `rowActions` and the selection all still work. On a narrow screen this is often the shape a table wants to take.

**Example — One column, and it stops looking like a table**

```html
<p class="kob-muted" style="margin:0 0 10px;font-size:13.5px">
  Same widget, same paging, same search box — one column and a formatter.
  Try the search field in the footer.
</p>
<div class="ex-grid" style="height:470px"></div>
```

```js
// A grid of one column has nothing to sort against another, nothing to
// resize, and no second column to filter by — so it drops the header
// furniture and the chip row and gets out of the way. What is left is
// a paged, searchable list, and the formatter decides what a row looks
// like. `showHeader: false` does the same to a grid of many columns.
Kob.datagrid(root.querySelector('.ex-grid'), {
  columns: [{
    field: 'tenant',
    title: 'Tenant',
    formatter: function (v, row) {
      var tone = row.status === 'paid' ? 'success'
        : row.status === 'overdue' ? 'danger' : 'warn';
      var initials = v.split(' ').map(function (word) { return word.charAt(0); })
        .join('').slice(0, 2).toUpperCase();
      return '' +
        '<div style="display:flex;align-items:center;gap:12px;padding:4px 2px">' +
          '<span class="kob-avatar">' + initials + '</span>' +
          '<div style="flex:1;min-width:0">' +
            '<div style="font-weight:600">' + v + '</div>' +
            '<div style="color:var(--kob-muted);font-size:12.5px">' +
              'Room ' + row.room + ' · ' + row.building + ' · due ' + row.due +
            '</div>' +
          '</div>' +
          '<div style="text-align:right">' +
            '<div style="font-weight:600">' + KOB_FMT.money(row.rent) + '</div>' +
            KOB_FMT.badge(row.status, tone) +
          '</div>' +
        '</div>';
    }
  }],
  data: KOB_SAMPLE.rows(40),
  pageSize: 5,
  striped: false,

  // The search box reads the text a formatter produced, so typing
  // 'overdue' or a room number finds the card that shows it.
  searchable: true,
  onClickRow: function (i, row) {
    Kob.toast({ msg: row.tenant + ' — room ' + row.room, type: 'info' });
  }
});
```

### Driving the grid from your own code

Every gesture the grid offers is a method underneath, and the chips and the footer are only one caller of them. A toolbar of your own, a keyboard shortcut or a route change can sort, search, filter, page and select exactly as a click does — and the matching event fires either way, so a status line has one place to listen.

**Example — Driving the grid from your own code**

```html
<p class="kob-muted" style="margin:0 0 10px;font-size:13.5px">
  Everything the grid does to itself, it will do on request. The chips and the
  footer are one caller of these methods; your toolbar is another.
</p>
<div class="kob-toolbar" style="border:1px solid var(--kob-border);border-bottom:none;border-radius:var(--kob-radius) var(--kob-radius) 0 0;flex-wrap:wrap">
  <a class="kob-linkbutton icon-sort" id="da-sort"><span class="kob-icon"></span>Rent, highest first</a>
  <a class="kob-linkbutton icon-search" id="da-search"><span class="kob-icon"></span>Search "thonglor"</a>
  <a class="kob-linkbutton icon-filter" id="da-filter"><span class="kob-icon"></span>Overdue only</a>
  <a class="kob-linkbutton icon-undo" id="da-reset"><span class="kob-icon"></span>Reset</a>
  <span class="kob-sep"></span>
  <a class="kob-linkbutton icon-ok" id="da-pick"><span class="kob-icon"></span>Select what is showing</a>
  <a class="kob-linkbutton icon-last" id="da-page"><span class="kob-icon"></span>Last page</a>
  <a class="kob-linkbutton icon-reload" id="da-load"><span class="kob-icon"></span>Load fresh rows</a>
</div>
<div class="ex-grid" style="height:420px"></div>
<div class="kob-statusbar" id="da-status" style="border:1px solid var(--kob-border);border-top:none"></div>
```

```js
var grid = Kob.datagrid(root.querySelector('.ex-grid'), {
  columns: [
    { field: 'room',     title: 'Room',     width: 90 },
    { field: 'tenant',   title: 'Tenant',   width: 160 },
    { field: 'building', title: 'Building', width: 130 },
    { field: 'rent',     title: 'Rent',     width: 110, align: 'right', formatter: KOB_FMT.money },
    { field: 'status',   title: 'Status',   width: 110, formatter: function (v) {
        return KOB_FMT.badge(v, v === 'paid' ? 'success' : v === 'overdue' ? 'danger' : 'warn');
      } }
  ],
  data: KOB_SAMPLE.rows(90),
  checkbox: true,
  pageSize: 7,

  // These three report what the grid did, whoever asked for it — a
  // chip, the footer, or one of the buttons above.
  onSortChange: function (field, order) { say('sorted by ' + field + ' ' + order); },
  onFilterChange: function (filters) { say(Object.keys(filters).length ? 'filtered' : 'filters cleared'); },
  onSelectionChange: function (rows) { say(rows.length + ' row(s) selected'); }
});

var status = root.querySelector('#da-status');
function say(what) {
  // getVisibleRows() is what survived the search, the chips and the
  // sort — not the page on screen, and not everything loaded.
  status.textContent = what + ' · ' + grid.getVisibleRows().length +
    ' of ' + grid.getRows().length + ' rows · ' + grid.pageCount() +
    ' page(s) · ' + grid.getSelectionCount() + ' selected';
}
say('ready');

// Pass an order to force one; leave it out to flip the column.
root.querySelector('#da-sort').onclick = function () { grid.sort('rent', 'desc'); };

// Exactly what typing into the footer box does, including filling it in.
root.querySelector('#da-search').onclick = function () { grid.search('thonglor'); };

// The four filter shapes: { in: [...] } picks from a list, { ge: n } is a
// lower bound, { q: 'text' } is contains, { eq: v } matches the raw field.
root.querySelector('#da-filter').onclick = function () {
  grid.setFilter('status', { in: ['overdue'] });
};

root.querySelector('#da-reset').onclick = function () {
  grid.clearFilters().search('').unselectAll().gotoPage(1);
  say('reset');
};

// Every row the filters let through — not only the seven on screen.
root.querySelector('#da-pick').onclick = function () { grid.selectAll(); };

root.querySelector('#da-page').onclick = function () { grid.gotoPage(grid.pageCount()); say('last page'); };

// loading() and loaded() drive the mask by hand, for work the grid
// knows nothing about — a report being built, rows arriving over a
// socket. loadData() replaces the rows and clears the selection with
// them, because they are new objects.
root.querySelector('#da-load').onclick = function () {
  grid.loading();
  setTimeout(function () {
    grid.loadData(KOB_SAMPLE.rows(30));
    grid.loaded();
    say('loaded 30 fresh rows');
  }, 600);
};
```

### A grid inside a tab, a panel or a dialog

Column widths are measured, and a grid built inside a hidden tab has nothing to measure. It watches its own box with a `ResizeObserver` and re-measures when the box changes, so in most cases this takes care of itself. The containers that hide and show their children — tabs, layout, panel, dialog — also fire a `kob-resize` event on what they reveal, which the grid listens for.

If a grid does turn up with collapsed columns after something outside the library changed the layout, `resize()` re-measures on demand. `fit: true` makes it fill its parent's height, which is usually what you want in a dialog or a layout region.

## filterbutton

The datagrid's filter chip, on its own — so a filter bar can sit above a chart, a card list, or anything else that is not a grid.

**Example — Filter buttons**

```html
<div style="display:flex;flex-wrap:wrap;gap:8px;align-items:center">
  <button class="kob-filterbutton" id="ex-f-building"></button>
  <button class="kob-filterbutton" id="ex-f-status"></button>
  <button class="kob-filterbutton" id="ex-f-rent"></button>
  <button class="kob-filterbutton" id="ex-f-name"></button>
  <a class="kob-linkbutton icon-cancel" id="ex-f-reset"><span class="kob-icon"></span>Reset</a>
</div>
<div class="ex-grid" style="height:280px;margin-top:12px"></div>
```

```js
var rows = KOB_SAMPLE.rows(137);

var grid = Kob.datagrid(root.querySelector('.ex-grid'), {
  columns: [
    { field: 'room',     title: 'Room',     width: 90 },
    { field: 'tenant',   title: 'Tenant',   width: 150 },
    { field: 'building', title: 'Building', width: 120 },
    { field: 'rent',     title: 'Rent',     width: 110, align: 'right', formatter: KOB_FMT.money },
    { field: 'status',   title: 'Status',   width: 110 }
  ],
  data: rows,
  filterable: false,          // the buttons above do the filtering
  pageSize: 20
});

// The chip from the grid's own toolbar, usable on its own — so a
// filter bar can live anywhere on the screen.
var filters = {};
function apply() {
  grid.loadData(rows.filter(function (r) {
    if (filters.building && filters.building.indexOf(r.building) === -1) { return false; }
    if (filters.status && filters.status.indexOf(r.status) === -1) { return false; }
    if (filters.rent !== undefined && filters.rent !== null && r.rent < filters.rent) { return false; }
    if (filters.tenant && r.tenant.toLowerCase().indexOf(filters.tenant.toLowerCase()) === -1) { return false; }
    return true;
  }));
}

Kob.filterbutton(root.querySelector('#ex-f-building'), {
  label: 'Building', options: KOB_SAMPLE.buildings,
  onChange: function (v) { filters.building = v; apply(); }
});
Kob.filterbutton(root.querySelector('#ex-f-status'), {
  label: 'Status', options: KOB_SAMPLE.statuses, multiple: false,
  onChange: function (v) { filters.status = v; apply(); }
});
Kob.filterbutton(root.querySelector('#ex-f-rent'), {
  label: 'Rent', kind: 'number',
  onChange: function (v) { filters.rent = v; apply(); }
});
Kob.filterbutton(root.querySelector('#ex-f-name'), {
  label: 'Tenant', kind: 'text',
  onChange: function (v) { filters.tenant = v; apply(); }
});

root.querySelector('#ex-f-reset').onclick = function () {
  ['building', 'status', 'rent', 'name'].forEach(function (key) {
    Kob.filterbutton(root.querySelector('#ex-f-' + key)).clear();
  });
  filters = {};
  apply();
};
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| label | string | `''` | Shown before the value: "Building: All". |
| kind | 'enum' \| 'text' \| 'number' | `'enum'` | Tick list, contains box, or lower bound. |
| options | array | `null` | enum only: `['Paid', 'Pending']` or `[{ value, text }]`. |
| value | string[] \| string \| number | `null` | Starting value. |
| multiple | boolean | `true` | `false` makes the list single-choice. |
| onChange | function(value) | — | string[] for enum, number, string, or `null`. |

**Methods:** `getValue()`, `setValue(v)`, `clear()`, `setOptions(list)`.

# Feedback

## messager and toasts

Each helper returns a promise, and still calls an old-style `fn` callback if you pass one.

**Example — Alerts, confirms, prompts and toasts**

```html
<div style="display:flex;flex-wrap:wrap;gap:8px;align-items:center">
  <a class="kob-linkbutton icon-tip" id="ex-m-alert"><span class="kob-icon"></span>Alert</a>
  <a class="kob-linkbutton icon-warn" id="ex-m-confirm"><span class="kob-icon"></span>Confirm</a>
  <a class="kob-linkbutton icon-edit" id="ex-m-prompt"><span class="kob-icon"></span>Prompt</a>
  <a class="kob-linkbutton icon-ok" id="ex-m-ok"><span class="kob-icon"></span>Success toast</a>
  <a class="kob-linkbutton icon-remove" id="ex-m-err"><span class="kob-icon"></span>Error toast</a>
</div>
<pre style="margin:12px 0 0;padding:10px 12px;border-radius:8px;background:var(--kob-accent-soft);font-size:12.5px" id="ex-m-out">the result of the last one shows here</pre>
```

```js
var out = root.querySelector('#ex-m-out');

// Each helper returns a promise, so it reads well with await too.
root.querySelector('#ex-m-alert').onclick = function () {
  Kob.alert({ title: 'Heads up', msg: 'Invoice 2026-0042 has been issued.' })
    .then(function (r) { out.textContent = 'alert resolved -> ' + r; });
};

root.querySelector('#ex-m-confirm').onclick = function () {
  Kob.confirm({ title: 'Delete', msg: 'Remove this tenant?' })
    .then(function (yes) { out.textContent = 'confirm resolved -> ' + yes; });
};

root.querySelector('#ex-m-prompt').onclick = function () {
  Kob.prompt({ title: 'Rename', msg: 'New room number:', value: '101/2' })
    .then(function (v) { out.textContent = 'prompt resolved -> ' + JSON.stringify(v); });
};

root.querySelector('#ex-m-ok').onclick = function () {
  Kob.toast({ msg: 'Saved successfully', type: 'success' });
};
root.querySelector('#ex-m-err').onclick = function () {
  Kob.toast({ msg: 'Could not reach the server', type: 'error' });
};
```

```js
if (await Kob.confirm({ title: 'Delete', msg: 'Remove this tenant?' })) {
  await api.remove(id);
  Kob.toast({ msg: 'Deleted', type: 'success' });
}

const name = await Kob.prompt({ title: 'Rename', msg: 'New name:', value: current });
if (name !== null) { rename(name); }
```

| Call | Resolves to |
| --- | --- |
| Kob.alert({ title, msg, html, icon }) | `true` |
| Kob.confirm({ title, msg }) | `true` or `false` |
| Kob.prompt({ title, msg, value }) | the typed string, or `null` |
| Kob.toast({ msg, type, timeout }) | `{ close(), element }` |

`icon` takes `'info'`, `'warn'` or `'error'`; toast `type` takes `'success'`, `'error'`, `'warn'` or `'info'`. Pass `html: true` to let `msg` carry markup.

## sweet

The big centred confirmation. [Kob.alert](https://kob-ui.com/docs.html#messager) and `Kob.confirm` draw a titled window, which is right for the dozens of small confirmations a data-entry app asks for. This is the other shape: one decision, front and centre, with a coloured mark that says at a glance whether the news is good.

```js
await Kob.sweet.success('Saved', 'Invoice 2026-0042 has been issued.');

if (await Kob.sweet({
  type: 'question',
  title: 'Delete this tenant?',
  msg: 'Room 112/3 becomes vacant. This cannot be undone.',
  showCancel: true,
  confirmText: 'Delete',
  cancelText: 'Keep',
  danger: true
})) {
  await api.remove(id);
}
```

> true
>
> false
>
> if (await Kob.sweet(…))
>
> undefined

| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| type | string | `'info'` | `success`, `error`, `warn`, `info`, `question`, or `''` for no mark. |
| title / msg | string | `''` | Heading and body. |
| html | boolean | `false` | Treat msg as markup. Only pass markup you produced yourself. |
| showCancel | boolean | `false` | Add the second button. |
| confirmText / cancelText | string | locale | Name the buttons after what they do, not OK and Cancel. |
| danger | boolean | `false` | Paint the confirm button as destructive. |
| timer | number | `0` | Auto-dismiss after n ms, resolving false. |
| closeOnBackdrop | boolean | `true` | A click on the dimmed page dismisses. |

`Kob.sweet.success`, `.error`, `.warn`, `.info` and `.question` are shorthands taking `(title, msg)` or the same options object.

**Example — Big confirmations**

```html
<div style="display:flex;flex-wrap:wrap;gap:8px;align-items:center">
  <a class="kob-linkbutton icon-check-circle" data-sweet="success"><span class="kob-icon"></span>Success</a>
  <a class="kob-linkbutton icon-x-circle"     data-sweet="error"><span class="kob-icon"></span>Error</a>
  <a class="kob-linkbutton icon-warn"         data-sweet="warn"><span class="kob-icon"></span>Warning</a>
  <a class="kob-linkbutton icon-tip"          data-sweet="info"><span class="kob-icon"></span>Info</a>
  <a class="kob-linkbutton kob-linkbutton-primary icon-remove" id="sw-delete"><span class="kob-icon"></span>Delete a tenant</a>
  <a class="kob-linkbutton icon-clock" id="sw-timer"><span class="kob-icon"></span>Auto-close</a>
  <code class="kob-muted" id="sw-out" style="font-size:12.5px">answer appears here</code>
</div>
```

```js
var out = root.querySelector('#sw-out');

var COPY = {
  success: ['Saved', 'Invoice 2026-0042 has been issued.'],
  error:   ['Could not save', 'The server refused the invoice number.'],
  warn:    ['Check the dates', 'The move-out date is before the move-in date.'],
  info:    ['Scheduled', 'Rent reminders go out at 09:00 tomorrow.']
};

root.querySelectorAll('[data-sweet]').forEach(function (btn) {
  btn.onclick = function () {
    var type = btn.getAttribute('data-sweet');
    Kob.sweet[type](COPY[type][0], COPY[type][1]);
  };
});

// The destructive one asks, and says so in the button rather than
// making the reader work out which of OK / Cancel deletes.
root.querySelector('#sw-delete').onclick = function () {
  Kob.sweet({
    type: 'question',
    title: 'Delete Tenant 12?',
    msg: 'Room 112/3 becomes vacant. This cannot be undone.',
    showCancel: true,
    confirmText: 'Delete',
    cancelText: 'Keep',
    danger: true
  }).then(function (yes) {
    out.textContent = yes ? 'deleted' : 'kept';
    if (yes) { Kob.toast({ msg: 'Tenant 12 deleted', type: 'warn' }); }
  });
};

root.querySelector('#sw-timer').onclick = function () {
  Kob.sweet({ type: 'info', title: 'Closing in 2s', msg: 'timer: 2000', timer: 2000 });
};
```

## statusbar

The strip along the bottom of a screen: what the app is doing, how many rows there are, who is signed in. CSS only — there is no widget to build and nothing to destroy.

```html
<div class="kob-statusbar">
  <span class="kob-status-item kob-status-ok"><i class="kob-status-dot"></i>Ready</span>
  <span class="kob-status-sep"></span>
  <span class="kob-status-item"><span class="kob-icon icon-table"></span><b>84</b> rows</span>
  <span class="kob-spacer"></span>
  <span class="kob-status-item"><span class="kob-icon icon-user"></span>admin</span>
</div>
```

| Class | What it is |
| --- | --- |
| kob-statusbar | The strip. Put it last inside a bordered box, or in a layout's south region. |
| kob-status-item | One entry. Aligns an icon, a dot and text on one line. |
| kob-status-dot | A coloured dot inside an item. |
| kob-status-sep | A vertical rule between groups. |
| kob-spacer | Pushes everything after it to the right. |
| kob-status-ok / -busy / -bad | On an item: colours its text and its dot green, amber or red. |

> and

**Example — Status bar**

```html
<div style="border:1px solid var(--kob-border);border-radius:var(--kob-radius);overflow:hidden">
  <div class="kob-toolbar" style="border-bottom:1px solid var(--kob-border)">
    <a class="kob-linkbutton icon-save" id="sb-save"><span class="kob-icon"></span>Save</a>
    <a class="kob-linkbutton icon-sync" id="sb-sync"><span class="kob-icon"></span>Sync</a>
    <a class="kob-linkbutton icon-ban" id="sb-break"><span class="kob-icon"></span>Break it</a>
  </div>
  <div id="sb-grid" style="height:210px"></div>
  <div class="kob-statusbar">
    <span class="kob-status-item" id="sb-state"><i class="kob-status-dot"></i><span>Ready</span></span>
    <span class="kob-status-sep"></span>
    <span class="kob-status-item"><span class="kob-icon icon-table"></span><span id="sb-rows"></span></span>
    <span class="kob-status-item"><span class="kob-icon icon-ok"></span><span id="sb-sel">no selection</span></span>
    <span class="kob-spacer"></span>
    <span class="kob-status-item"><span class="kob-icon icon-user"></span>admin</span>
    <span class="kob-status-sep"></span>
    <span class="kob-status-item" id="sb-saved">saved just now</span>
  </div>
</div>
```

```js
var rows = KOB_SAMPLE.rows(60);
var state = root.querySelector('#sb-state');

var grid = Kob.datagrid(root.querySelector('#sb-grid'), {
  columns: [
    { field: 'room',   title: 'Room',   width: 80 },
    { field: 'tenant', title: 'Tenant', width: 150 },
    { field: 'rent',   title: 'Rent',   width: 100, align: 'right', formatter: KOB_FMT.money }
  ],
  data: rows,
  filterable: false,
  pagination: false,
  fit: true,
  onClickRow: function (i, row) {
    root.querySelector('#sb-sel').textContent = row.room + ' selected';
  }
});

root.querySelector('#sb-rows').textContent = rows.length + ' rows';

// Three states, one element: the class carries the colour and the dot,
// the text says what it means. Colour alone would leave the state
// invisible to anyone who cannot separate green from amber.
function setState(kind, text) {
  state.className = 'kob-status-item kob-status-' + kind;
  state.lastChild.textContent = text;
}

root.querySelector('#sb-save').onclick = function () {
  setState('busy', 'Saving…');
  setTimeout(function () {
    setState('ok', 'Ready');
    root.querySelector('#sb-saved').textContent = 'saved at ' + new Date().toLocaleTimeString();
  }, 900);
};

root.querySelector('#sb-sync').onclick = function () {
  setState('busy', 'Syncing…');
  setTimeout(function () { setState('ok', 'Up to date'); }, 1200);
};

root.querySelector('#sb-break').onclick = function () {
  setState('bad', 'Connection lost');
};

setState('ok', 'Ready');
```

## alert

The banner that stays on the page — a validation summary above a form, a warning across the top of a screen.

> **Two different things share the word.** `Kob.alert()` opens a *modal dialog*. This inline banner is `Kob.alertbox()`, or `class="kob-alert"` in markup.

**Example — Inline alerts and badges**

```html
<div style="max-width:620px">
  <div class="kob-alert" data-options="type:'info'">Rent for March has not been invoiced yet.</div>
  <div class="kob-alert" id="ex-alert-ok" data-options="type:'success',title:'Saved'">All 137 rows were written.</div>
  <div class="kob-alert" id="ex-alert-warn" data-options="type:'warn',title:'Check the meter readings',closable:true">
    Three rooms have a reading lower than last month.
  </div>
  <div class="kob-alert" id="ex-alert-danger" data-options="type:'danger',title:'Save failed',closable:true">
    The server refused the request.
  </div>

  <div style="display:flex;gap:10px;align-items:center;flex-wrap:wrap;margin-top:16px">
    <a class="kob-linkbutton icon-mail" id="ex-badge-btn"><span class="kob-icon"></span>Inbox <span class="kob-badge kob-badge-danger" id="ex-badge">3</span></a>
    <a class="kob-linkbutton icon-add" id="ex-badge-inc"><span class="kob-icon"></span>One more</a>
    <span class="kob-badge kob-badge-success">Paid</span>
    <span class="kob-badge kob-badge-warn">Pending</span>
    <span class="kob-badge kob-badge-danger">Overdue</span>
    <span class="kob-badge kob-badge-accent">New</span>
    <span class="kob-badge kob-badge-muted">Draft</span>
  </div>
</div>
```

```js
// Kob.alert() opens a modal. The inline banner is Kob.alertbox(),
// or class="kob-alert" picked up by the parser — as above.
var badge = Kob.badge(root.querySelector('#ex-badge'), { type: 'danger', max: 99 });
root.querySelector('#ex-badge-inc').onclick = function () { badge.increment(); };

// Built from script rather than markup, and dismissed after a while.
Kob.alertbox(root.querySelector('#ex-alert-ok')).setMessage('All 137 rows were written.');
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| type | 'info' \| 'success' \| 'warn' \| 'danger' | `'info'` | Colour and icon. |
| title | string | `''` | Bold line above the message. |
| msg | string | — | Body. Omit to keep what is already in the markup. |
| html | boolean | `false` | Treat title and message as HTML. |
| iconCls | string \| false | by type | Override or remove the icon. |
| closable | boolean | `false` | Adds a dismiss button. |
| timeout | number | `0` | Dismiss by itself after this many ms. |
| onClose | function | — |   |

**Methods:** `setMessage(s)`, `setType(t)`, `close()`.

## badge

Static badges are markup. The widget is for the ones that change — an unread count on a toolbar button, a status that flips as data arrives.

```html
<span class="kob-badge kob-badge-success">Paid</span>
<span class="kob-badge kob-badge-danger">Overdue</span>
<span class="kob-badge kob-badge-dot kob-badge-warn"></span>
```

```js
const unread = Kob.badge('#inbox-count', { type: 'danger', max: 99 });
unread.increment();          // 3 -> 4
unread.setText(250);         // shows 99+
unread.setText(0);           // hides itself
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| text | string \| number | markup | What is shown. |
| type | string | `'muted'` | `muted`, `accent`, `success`, `warn`, `danger`, `info`. |
| dot | boolean | `false` | A coloured dot with no text. |
| max | number | `99` | Counts above this show as "99+". |
| hideEmpty | boolean | `true` | Hide at 0 or empty. |

**Methods:** `setText(v)`, `getText()`, `setType(t)`, `increment(by)`.

## progressbar

A measured fill, or a sweeping stripe while the length of the job is unknown.

**Example — Progress and spinners**

```html
<div style="max-width:520px">
  <div class="kob-progressbar" id="ex-pb"></div>
  <div class="kob-progressbar" id="ex-pb-striped" style="margin-top:10px"></div>
  <div class="kob-progressbar" id="ex-pb-wait" style="margin-top:10px"></div>
  <div style="display:flex;gap:8px;margin-top:12px;flex-wrap:wrap;align-items:center">
    <a class="kob-linkbutton icon-forward" id="ex-pb-run"><span class="kob-icon"></span>Run a job</a>
    <a class="kob-linkbutton icon-reload" id="ex-pb-reset"><span class="kob-icon"></span>Reset</a>
    <span class="kob-spinner kob-spinner-sm"></span>
    <span class="kob-spinner kob-spinner-md"></span>
    <span class="kob-spinner kob-spinner-lg"></span>
  </div>
  <div id="ex-pre" style="position:relative;height:120px;margin-top:14px;border:1px solid var(--kob-border);border-radius:10px;padding:14px">
    <b>A panel that goes busy</b>
    <p style="margin:6px 0 0;color:var(--kob-muted);font-size:13.5px">Kob.loading() covers it and hands back the uncover function.</p>
  </div>
  <a class="kob-linkbutton icon-clock" id="ex-pre-go" style="margin-top:10px"><span class="kob-icon"></span>Cover it for 2s</a>
</div>
```

```js
var bar = Kob.progressbar(root.querySelector('#ex-pb'), {
  value: 35,
  onComplete: function () { Kob.toast({ msg: 'Finished', type: 'success' }); }
});
Kob.progressbar(root.querySelector('#ex-pb-striped'), {
  value: 70, type: 'warn', striped: true
});
// No total to measure against: a sweeping stripe instead of a fill.
Kob.progressbar(root.querySelector('#ex-pb-wait'), {
  indeterminate: true, type: 'success', height: 8
});

root.querySelector('#ex-pb-run').onclick = function () {
  var v = 0;
  var timer = setInterval(function () {
    v += 7;
    bar.setValue(v);
    if (v >= 100) { clearInterval(timer); }
  }, 120);
};
root.querySelector('#ex-pb-reset').onclick = function () { bar.setValue(0); };

root.querySelector('#ex-pre-go').onclick = function () {
  var done = Kob.loading(root.querySelector('#ex-pre'), 'Fetching invoices...');
  setTimeout(done, 2000);
};
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| value | number | `0` | 0-100, clamped. |
| indeterminate | boolean | `false` | Sweeping stripe; no percentage shown. |
| text | string \| false | `'{value}%'` | Label template; `false` for none. |
| height | number | `20` | Bar height in pixels. |
| type | string | `'accent'` | `accent`, `success`, `warn`, `danger`. |
| striped | boolean | `false` | Moving stripes on the fill. |
| onChange / onComplete | function | — | `onComplete` fires once, when the value first reaches 100. |

**Methods:** `setValue(n)`, `getValue()`, `indeterminate(on)`.

## preloader and spinner

Over an element it is a busy mask; over `<body>` it is the splash the page shows before the application has drawn anything.

```js
// The one-liner: cover, work, uncover.
const done = Kob.loading('#panel', 'Fetching invoices...');
await api.load();
done();

// Or keep the widget and drive it.
const splash = Kob.preloader(document.body, { size: 'lg', msg: 'Starting' });
splash.setMessage('Loading settings');
splash.hide();
```

The spinner on its own is a class, with three sizes:

```html
<span class="kob-spinner kob-spinner-sm"></span>
<span class="kob-spinner kob-spinner-md"></span>
<span class="kob-spinner kob-spinner-lg"></span>
```

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| msg | string | `''` | Caption under the spinner. |
| size | 'sm' \| 'md' \| 'lg' | `'md'` |   |
| visible | boolean | `true` | `false` builds it hidden. |
| backdrop | boolean | `true` | Dim what is underneath. |
| timeout | number | `0` | Hide by itself after this many ms. |

**Methods:** `show(msg)`, `hide()`, `isVisible()`, `setMessage(s)`.

A static element gets `position: relative` so the cover has something to sit against; `destroy()` puts that back.

# Layout CSS

## Grid, flex and button groups

Enough layout CSS to lay out a form or a dashboard without reaching for a whole framework. Deliberately small.

### The 12-column row

```html
<div class="kob-row">
  <div class="kob-col-8">main</div>
  <div class="kob-col-4">side</div>
</div>
```

Below 720px every column takes the full width — one honest breakpoint rather than a matrix of per-size classes. For cards and tiles, `kob-autogrid` fits as many columns as it can:

```html
<div class="kob-autogrid">…</div>                    <!-- min 260px -->
<div class="kob-autogrid kob-autogrid-sm">…</div>    <!-- min 180px -->
<div class="kob-autogrid" style="--kob-min:320px">…</div>
```

### Flex helpers

| Class | Does |
| --- | --- |
| kob-flex / kob-inline-flex | Flex container with the standard gap. |
| kob-flex-col / kob-flex-wrap | Direction and wrapping. |
| kob-items-start / -center / -end / -baseline / -stretch | Cross-axis alignment. |
| kob-justify-start / -center / -end / -between / -around | Main-axis alignment. |
| kob-grow / kob-none | Take the slack, or refuse to. |
| kob-spacer | An empty element that pushes what follows to the far end. |
| kob-gap-0 … kob-gap-5 | Gap scale: 0, 6, 10, 14, 20, 28px. |
| kob-p-0 … kob-p-4, kob-mt-*, kob-mb-* | Padding and vertical margin on the same scale. |
| kob-fill / kob-w-full / kob-h-full / kob-scroll | Sizing and overflow. |
| kob-truncate / kob-muted / kob-small / kob-strong / kob-text-* | Text. |

### Button groups and toolbars

```html
<div class="kob-btn-group">
  <button class="kob-btn selected">Rows</button>
  <button class="kob-btn">Cards</button>
  <button class="kob-btn">Chart</button>
</div>

<div class="kob-toolbar">
  <a class="kob-linkbutton icon-add"><span class="kob-icon"></span>New</a>
  <span class="kob-sep"></span>
  <a class="kob-linkbutton icon-print"><span class="kob-icon"></span>Print</a>
  <span class="kob-spacer"></span>
  <a class="kob-linkbutton icon-settings"><span class="kob-icon"></span></a>
</div>
```

Keep `selected` on one member and the group reads as a segmented control. `kob-btn-group-vertical` stacks it.

# Extend

## React, Vue and Angular

kob-ui is not a component library — it builds DOM imperatively. That works inside any framework, on one condition: give it an element the framework will leave alone, and destroy the widget when that element goes away.

> **The rule.** Render an empty container, hand it to kob-ui, and never render children into it yourself. Everything inside belongs to the widget; everything outside belongs to your framework.

`destroy()` takes back every node the widget added and returns the element as it found it, so mounting again on the same element is safe — which is what React's StrictMode does in development, and what any router does when you revisit a screen.

### React

```js useKob.js
import { useEffect, useRef } from 'react';
import Kob from 'kob-ui';
import 'kob-ui/css';

/** Builds a widget on mount and destroys it on unmount. */
export function useKob(widget, options, deps = []) {
  const ref = useRef(null);
  const instance = useRef(null);

  useEffect(() => {
    instance.current = Kob[widget](ref.current, options);
    return () => {
      instance.current.destroy();
      instance.current = null;
    };
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, deps);

  return [ref, instance];
}
```

```js OrderGrid.jsx
function OrderGrid({ onPick }) {
  const [ref, grid] = useKob('datagrid', {
    columns: [
      { field: 'room',   title: 'Room',   width: 100 },
      { field: 'tenant', title: 'Tenant', width: 180 }
    ],
    url: '/api/rooms',
    onClickRow: (i, row) => onPick(row)
  });

  // Drive it later through the ref — never by re-rendering into the div.
  const refresh = () => grid.current.reload();

  return (
    <>
      Refresh
      
    
  );
}
			

			Vue 3
			
<script setup>
import { ref, onMounted, onBeforeUnmount, shallowRef } from 'vue';
import Kob from 'kob-ui';
import 'kob-ui/css';

const host = ref(null);
const grid = shallowRef(null);      // shallowRef: never make a widget reactive

onMounted(() => {
  grid.value = Kob.datagrid(host.value, {
    columns: [{ field: 'room', title: 'Room', width: 100 }],
    url: '/api/rooms'
  });
});

onBeforeUnmount(() => grid.value?.destroy());

defineExpose({ reload: () => grid.value.reload() });
</script>

<template>
  <div ref="host" style="height: 420px"></div>
</template>
			

			Angular
			
import { Directive, ElementRef, Input, OnInit, OnDestroy } from '@angular/core';
import Kob from 'kob-ui';

@Directive({ selector: '[kobDatagrid]', standalone: true })
export class KobDatagridDirective implements OnInit, OnDestroy {
  @Input('kobDatagrid') options: any = {};
  private grid: any;

  constructor(private host: ElementRef<HTMLElement>) {}

  ngOnInit() {
    this.grid = Kob.datagrid(this.host.nativeElement, this.options);
  }

  ngOnDestroy() {
    this.grid?.destroy();
  }

  reload() { this.grid.reload(); }
}

// <div [kobDatagrid]="{ columns, url: '/api/rooms' }" style="height:420px"></div>
			
			
				Widget callbacks fire outside Angular's zone by default. If a change
				detection cycle needs to follow one, wrap it:
				this.zone.run(() => …).
			

			Things to watch
			
				
					SituationWhat to do
					
						
							Data changed
							Call grid.loadData(rows) from an effect or watcher. Do not rebuild the widget.
						
						
							Options changed
							Kob.datagrid(el, { pageSize: 100 }) merges and refreshes in place.
						
						
							A cell needs a framework component
							A formatter returns an HTML string, not JSX. For rich cells, render into the row element from onLoadSuccess, or keep the cell simple and open a dialog on click.
						
						
							Server rendering
							Widgets touch the DOM, so build them in a client-only lifecycle hook — useEffect, onMounted, ngOnInit in the browser.
						
						
							Strict mode double mount
							Handled: destroy() restores the element, so the second mount produces exactly one widget.
```

## Custom widgets

Extend `Kob.Widget` and register it. From then on it behaves like a built-in: `Kob.parse()` builds it from markup, `data-options` works, and the accessor returns the instance.

**Example — Writing your own widget**

```html
<div style="max-width:420px">
  <div class="kob-rating" data-options="value:3"></div>
  <p style="margin:10px 0 0;color:var(--kob-muted);font-size:13.5px" id="ex-rating-out"></p>
</div>
```

```js
// Extend Kob.Widget, register it, and Kob.parse() will build it from
// markup exactly like a built-in — data-options and all.
class Rating extends Kob.Widget {
  static widgetName = 'rating';
  static defaults = { max: 5, value: 0, onChange: null };

  init() {
    this.render();
    this.track(Kob.dom.on(this.el, 'click', '[data-n]', (e, star) => {
      this.setValue(Number(star.dataset.n));
    }));
  }

  setValue(v) {
    this.options.value = v;
    this.render();
    this.emit('onChange', v);
    return this;
  }

  getValue() { return this.options.value; }

  render() {
    var html = '';
    for (var n = 1; n <= this.options.max; n++) {
      html += '<span data-n="' + n + '" class="kob-icon icon-star" style="' +
        'cursor:pointer;width:22px;height:22px;color:' +
        (n <= this.options.value ? 'var(--kob-accent)' : 'var(--kob-border)') + '"></span>';
    }
    this.el.innerHTML = html;
  }
}

if (!Kob.registry.has('rating')) { Kob.rating = Kob.register(Rating); }

var out = root.querySelector('#ex-rating-out');
var widget = Kob.rating(root.querySelector('.kob-rating'), {
  onChange: function (v) { out.textContent = 'rated ' + v + ' / 5'; }
});
out.textContent = 'rated ' + widget.getValue() + ' / 5';
```

| Member | Description |
| --- | --- |
| static widgetName | Drives the class name: `'rating'` → `class="kob-rating"`. |
| static defaults | Merged under `data-options` and the constructor argument. |
| this.el | The element the widget is mounted on. |
| this.options | The resolved options. |
| init() | Build the DOM. Called by the constructor. |
| refresh() | Called when new options arrive after construction. |
| track(off) | Register a cleanup function — pass the unbinder `Kob.dom.on` returns. |
| emit(hook, ...args) | Fire an option callback with the element as `this`. |
| destroy() | Runs every tracked cleanup. Extend it, then call `super.destroy()`. |

## Kob reference

| Member | Description |
| --- | --- |
| Kob.version | The library version. |
| Kob.parse(root) / unparse(root) / autoParse() | Build or tear down the widgets declared in markup. |
| Kob.parseOptions(str) | Read the inline `data-options` syntax. |
| Kob.instance(el, name) | The widget of that name on an element, if any. |
| Kob.config | `request`, `onRequestError`, `prefix`, `zIndex`, `locale`. |
| Kob.locale(name?) / addLocale(name, bundle) / locales / t(key, vars) | Localisation. |
| Kob.zIndex() | Next z-index for a floating layer, shared by every widget. |
| Kob.Widget / register(Class) / registry | Extension points. |
| Kob.dom | The internal DOM helpers: `on`, `el`, `append`, `css`, `escapeHtml`, … |
| Kob.date | `parseDate`, `formatDate`, `toISO`, `today`. |
| Kob.classes | The widget classes themselves, for `extends`. |

# Recipes — complete screens

## A complete screen

A bar across the top, a menu down the left, a toolbar, a grid, and an editor dialog with validation — the shape most internal tools end up in. Around a hundred lines, no framework.

**Example — A complete screen: navbar, sidebar, grid, editor dialog**

```html
<div class="kob-appshell" id="ex-admin" style="height:660px;border:1px solid var(--kob-border);border-radius:12px">

  <!-- the bar across the top -->
  <header class="kob-appbar">
    <button class="kob-appbar-btn" id="ad-rail" title="Collapse the menu"><span class="kob-icon icon-sidebar"></span></button>
    <span class="kob-appbar-brand"><span class="kob-appbar-mark">R</span>RentRoll</span>
    <span class="kob-sep"></span>
    <input class="kob-searchbox" id="ad-find" style="width:240px" data-options="prompt:'Search room or tenant'">
    <span class="kob-spacer"></span>
    <button class="kob-appbar-btn" id="ad-bell" title="Notifications">
      <span class="kob-icon icon-bell"></span><span class="kob-badge kob-badge-danger">3</span>
    </button>
    <button class="kob-appbar-btn" id="ad-help" title="Help"><span class="kob-icon icon-question"></span></button>
    <span class="kob-sep"></span>
    <button class="kob-appbar-user" id="ad-account">
      <span class="kob-avatar">SP</span>
      <span class="kob-appbar-user-lines">
        <span class="kob-appbar-user-name">Somchai P.</span>
        <span class="kob-appbar-user-role">Administrator</span>
      </span>
      <span class="kob-icon icon-chevron-down"></span>
    </button>
  </header>

  <!-- the menu down the left -->
  <nav class="kob-sidebar">
    <div class="kob-sidebar-title">Overview</div>
    <a class="kob-sidebar-item" data-page="Dashboard" title="Dashboard"><span class="kob-icon icon-dashboard"></span><span class="kob-sidebar-label">Dashboard</span></a>
    <a class="kob-sidebar-item active" data-page="Rent roll" title="Rent roll"><span class="kob-icon icon-table"></span><span class="kob-sidebar-label">Rent roll</span><span class="kob-badge kob-badge-accent">84</span></a>
    <a class="kob-sidebar-item" data-page="Invoices" title="Invoices"><span class="kob-icon icon-invoice"></span><span class="kob-sidebar-label">Invoices</span><span class="kob-badge kob-badge-danger">28</span></a>
    <div class="kob-sidebar-title">Buildings</div>
    <div id="ad-buildings" style="display:flex;flex-direction:column;gap:2px"></div>
    <div class="kob-sidebar-title">Manage</div>
    <a class="kob-sidebar-item" data-page="Tenants" title="Tenants"><span class="kob-icon icon-users"></span><span class="kob-sidebar-label">Tenants</span></a>
    <a class="kob-sidebar-item" data-page="Reports" title="Reports"><span class="kob-icon icon-chart-line"></span><span class="kob-sidebar-label">Reports</span></a>
    <a class="kob-sidebar-item" data-page="Settings" title="Settings"><span class="kob-icon icon-settings"></span><span class="kob-sidebar-label">Settings</span></a>
    <div class="kob-spacer"></div>
    <div class="kob-sidebar-sep"></div>
    <a class="kob-sidebar-item" data-page="Sign out" title="Sign out"><span class="kob-icon icon-logout"></span><span class="kob-sidebar-label">Sign out</span></a>
  </nav>

  <!-- the page itself -->
  <main class="kob-appmain" style="display:flex;flex-direction:column;overflow:hidden">
    <div class="kob-pagehead">
      <div>
        <div class="kob-crumbs"><span>RentRoll</span><span id="ad-crumb">Rent roll</span></div>
        <h3 id="ad-title">Rent roll</h3>
      </div>
      <div class="kob-spacer"></div>
      <a class="kob-linkbutton icon-download" id="ad-export"><span class="kob-icon"></span>Export</a>
      <a class="kob-linkbutton kob-linkbutton-primary icon-add" id="ad-new"><span class="kob-icon"></span>New tenant</a>
    </div>

    <div class="kob-card" style="flex:1;min-height:0;display:flex;flex-direction:column;overflow:hidden">
      <div class="kob-toolbar">
        <a class="kob-linkbutton icon-edit" id="ad-edit"><span class="kob-icon"></span>Edit</a>
        <a class="kob-linkbutton icon-remove" id="ad-del"><span class="kob-icon"></span>Delete</a>
        <span class="kob-sep"></span>
        <a class="kob-linkbutton icon-reload" id="ad-reload"><span class="kob-icon"></span>Reload</a>
        <span class="kob-spacer"></span>
        <span class="kob-muted" id="ad-scope" style="font-size:12.5px"></span>
      </div>
      <div id="ad-grid" style="flex:1;min-height:0"></div>
    </div>
  </main>

  <div class="kob-statusbar kob-appfoot">
    <span class="kob-status-item kob-status-ok"><i class="kob-status-dot"></i>Connected</span>
    <span class="kob-status-sep"></span>
    <span class="kob-status-item" id="ad-count"></span>
    <span class="kob-spacer"></span>
    <span class="kob-status-item"><span class="kob-icon icon-user"></span>Somchai P.</span>
  </div>
</div>

<div id="ad-dialog" style="display:none">
  <form class="kob-form" id="ad-form">
    <input class="kob-textbox"   name="room"   data-options="label:'Room',labelWidth:90,required:true">
    <input class="kob-textbox"   name="tenant" data-options="label:'Tenant',labelWidth:90,required:true">
    <input class="kob-combobox"  name="building" id="ad-building" data-options="label:'Building',labelWidth:90,editable:false">
    <input class="kob-numberbox" name="rent"   data-options="label:'Rent',labelWidth:90,precision:2,min:0">
    <input class="kob-datebox"   name="due"    data-options="label:'Due',labelWidth:90">
    <input type="checkbox" class="kob-checkbox" name="active" data-options="label:'Active'">
  </form>
</div>
```

```js
var rows = KOB_SAMPLE.rows(84);
var shell = root.querySelector('#ex-admin');
var current = null;

/* ---- the grid the whole screen is about ---- */

var grid = Kob.datagrid(root.querySelector('#ad-grid'), {
  columns: [
    { field: 'room',     title: 'Room',     width: 90 },
    { field: 'tenant',   title: 'Tenant',   width: 160 },
    { field: 'building', title: 'Building', width: 120 },
    { field: 'rent',     title: 'Rent',     width: 110, align: 'right', formatter: KOB_FMT.money },
    { field: 'due',      title: 'Due',      width: 105 },
    { field: 'status',   title: 'Status',   width: 105, formatter: function (v) {
        return KOB_FMT.badge(v, v === 'paid' ? 'success' : v === 'overdue' ? 'danger' : 'warn');
      } }
  ],
  data: rows,
  fit: true,
  rownumbers: true,
  pageSize: 20,
  onClickRow: function (i, row) { current = row; },
  onDblClickRow: function () { edit(); }
});

/* ---- the bar across the top ---- */

// Collapsing the menu to a rail is one class on the shell; the
// stylesheet drops the labels and narrows the column.
root.querySelector('#ad-rail').onclick = function () {
  shell.classList.toggle('kob-sidebar-collapsed');
};

Kob.searchbox(root.querySelector('#ad-find'), {
  delay: 200,
  onSearch: function (q) { grid.search(q); showCount(); }
});

// A menu hanging off a button in the bar. The button stays lit for as
// long as its menu is up, so a click always shows where it landed —
// and clicking again puts it away.
function menuButton(sel, items) {
  var button = root.querySelector(sel);
  var menu = Kob.menu(document.createElement('div'), {
    items: items,
    onClick: function (item) { Kob.toast(item.text); },
    onShow: function () { button.classList.add('active'); },
    onHide: function () { button.classList.remove('active'); }
  });
  button.onclick = function () {
    if (menu.isOpen()) { menu.hide(); } else { menu.showFor(button); }
  };
}

menuButton('#ad-bell', [
  { text: '3 invoices went overdue today', iconCls: 'icon-warn' },
  { text: 'Tenant 12 paid 8,250.00',       iconCls: 'icon-banknote' },
  { text: 'Tenant 85 moved into 118/2',    iconCls: 'icon-user-plus' },
  { separator: true },
  { text: 'Mark all as read',              iconCls: 'icon-check-circle' }
]);

menuButton('#ad-account', [
  { text: 'Profile',     iconCls: 'icon-user' },
  { text: 'Preferences', iconCls: 'icon-sliders' },
  { separator: true },
  { text: 'Sign out',    iconCls: 'icon-logout' }
]);

root.querySelector('#ad-help').onclick = function () {
  Kob.sweet.info('Rent roll', 'Pick a building down the side, then edit a room — or double-click one.');
};
root.querySelector('#ad-export').onclick = function () { Kob.toast('Exporting the rent roll'); };

/* ---- the menu down the left ---- */

// Routing is the application's business — the shell only marks which
// entry is current and repaints the heading above the content.
var pages = root.querySelectorAll('.kob-sidebar-item[data-page]');
pages.forEach(function (link) {
  link.onclick = function () {
    var name = link.getAttribute('data-page');
    if (name === 'Sign out') { Kob.toast('Signed out'); return; }
    pages.forEach(function (other) { other.classList.remove('active'); });
    link.classList.add('active');
    root.querySelector('#ad-title').textContent = name;
    root.querySelector('#ad-crumb').textContent = name;
  };
});

// The building list is part of the same menu, but it drives the grid's
// own filter API rather than the heading.
var scope = root.querySelector('#ad-scope');
var list = root.querySelector('#ad-buildings');

['All buildings'].concat(KOB_SAMPLE.buildings).forEach(function (name, i) {
  var a = document.createElement('a');
  a.className = 'kob-sidebar-item' + (i === 0 ? ' active' : '');
  a.title = name;
  a.innerHTML = '<span class="kob-icon ' + (i ? 'icon-building' : 'icon-apps') + '"></span>' +
    '<span class="kob-sidebar-label">' + name + '</span>';
  a.onclick = function () {
    list.querySelectorAll('a').forEach(function (n) { n.classList.remove('active'); });
    a.classList.add('active');
    if (i === 0) { grid.clearFilters(); }
    else { grid.setFilter('building', { in: [name.toLowerCase()] }); }
    scope.textContent = name;
    showCount();
  };
  list.appendChild(a);
});
scope.textContent = 'All buildings';

/* ---- the editor ---- */

var form = Kob.form(root.querySelector('#ad-form'));
Kob.combobox(root.querySelector('#ad-building'), {
  data: KOB_SAMPLE.buildings.map(function (b) { return { id: b, text: b }; })
});

var dialog = Kob.dialog(root.querySelector('#ad-dialog'), {
  title: 'Tenant', width: 440,
  buttons: [
    { text: 'Cancel', iconCls: 'icon-cancel', handler: function (d) { d.close(); } },
    { text: 'Save', iconCls: 'icon-save', primary: true, handler: save }
  ]
});

function edit() {
  if (!current) { return Kob.alert({ title: 'Pick a row', msg: 'Select a row first.' }); }
  form.setValues(current);
  dialog.setTitle('Edit ' + current.room).open();
}

function save(d) {
  if (!form.validate()) { return; }
  Object.assign(current || (current = { id: Date.now(), status: 'pending' }), form.getValues());
  if (rows.indexOf(current) === -1) { rows.unshift(current); }
  grid.loadData(rows);
  showCount();
  Kob.toast({ msg: 'Saved ' + current.room, type: 'success' });
  d.close();
}

root.querySelector('#ad-new').onclick = function () {
  current = null;
  form.clear();
  dialog.setTitle('New tenant').open();
};
root.querySelector('#ad-edit').onclick = edit;
root.querySelector('#ad-del').onclick = function () {
  if (!current) { return Kob.alert({ title: 'Pick a row', msg: 'Select a row first.' }); }
  Kob.confirm({ title: 'Delete', msg: 'Remove ' + current.room + '?' }).then(function (yes) {
    if (!yes) { return; }
    rows.splice(rows.indexOf(current), 1);
    current = null;
    grid.loadData(rows);
    showCount();
    Kob.toast({ msg: 'Deleted', type: 'warn' });
  });
};
root.querySelector('#ad-reload').onclick = function () {
  rows = KOB_SAMPLE.rows(84);
  current = null;
  grid.loadData(rows);
  showCount();
  Kob.toast('Reloaded');
};

/* ---- the line along the bottom ---- */

function showCount() {
  root.querySelector('#ad-count').innerHTML =
    '<b>' + grid.getVisibleRows().length + '</b> of ' + rows.length + ' rooms';
}
showCount();
```

## Whole screens

The three screens every internal tool starts with — a sign-in, a sign-up, and the dashboard everyone lands on afterwards, that one with the bar, the sidebar and the status line an application actually ships with.

**Example — Sign in**

```html
<div style="display:flex;justify-content:center;padding:8px 0">
  <div class="kob-card" style="width:min(360px,100%)">
    <div class="kob-card-body">
      <div style="text-align:center;margin-bottom:18px">
        <span class="kob-icon icon-lock" style="width:30px;height:30px;color:var(--kob-accent)"></span>
        <h3 style="margin:8px 0 2px;font-size:19px">Welcome back</h3>
        <p style="margin:0;color:var(--kob-muted);font-size:13px">Sign in to the rent roll</p>
      </div>
      <div id="lg-error" class="kob-alert kob-alert-danger" style="display:none;margin-bottom:12px"></div>
      <form id="lg-form" onsubmit="return false">
        <input class="kob-textbox"     name="user" data-options="label:'User',labelWidth:80,prompt:'admin',required:true">
        <input class="kob-passwordbox" name="pass" data-options="label:'Password',labelWidth:80,prompt:'••••••••',required:true">
        <div style="display:flex;align-items:center;justify-content:space-between;margin:4px 0 16px">
          <input type="checkbox" class="kob-checkbox" name="remember" data-options="label:'Remember me'">
          <a href="javascript:;" style="font-size:13px;color:var(--kob-accent)">Forgot?</a>
        </div>
        <a class="kob-linkbutton kob-linkbutton-primary icon-login" id="lg-go" style="width:100%;justify-content:center">
          <span class="kob-icon"></span>Sign in</a>
      </form>
    </div>
  </div>
</div>
```

```js
var form = Kob.form(root.querySelector('#lg-form'));
var error = root.querySelector('#lg-error');
var button = root.querySelector('#lg-go');

function fail(message) {
  error.textContent = message;
  error.style.display = '';
}

root.querySelector('#lg-go').onclick = function () {
  error.style.display = 'none';

  // validate() marks every invalid field and returns false, so the
  // banner only has to say what the fields cannot.
  if (!form.validate()) { return fail('Fill in both fields.'); }

  var values = form.read();
  Kob.linkbutton(button, { disabled: true, text: 'Signing in…' });

  // Stand-in for the real POST.
  setTimeout(function () {
    Kob.linkbutton(button, { disabled: false, text: 'Sign in' });

    if (values.user !== 'admin' || values.pass !== 'admin') {
      return fail('That user and password do not match.');
    }
    Kob.sweet.success('Signed in', 'Welcome back, ' + values.user + '.');
  }, 600);
};

// Enter anywhere in the form submits, the way a login is expected to.
root.querySelector('#lg-form').addEventListener('keydown', function (e) {
  if (e.key === 'Enter') { e.preventDefault(); button.click(); }
});

// Try admin / admin.
```

**Example — Create an account**

```html
<form id="rg-form" onsubmit="return false" style="max-width:620px">
  <div class="kob-row">
    <div class="kob-col-6"><input class="kob-textbox" name="first" data-options="label:'First name',labelPosition:'top',required:true"></div>
    <div class="kob-col-6"><input class="kob-textbox" name="last"  data-options="label:'Last name',labelPosition:'top',required:true"></div>
  </div>
  <input class="kob-textbox" name="email" data-options="label:'Email',labelPosition:'top',prompt:'you@example.com',required:true">
  <div class="kob-row">
    <div class="kob-col-6"><input class="kob-passwordbox" name="pass"  data-options="label:'Password',labelPosition:'top',required:true"></div>
    <div class="kob-col-6"><input class="kob-passwordbox" name="pass2" data-options="label:'Repeat password',labelPosition:'top',required:true"></div>
  </div>
  <div id="rg-strength" style="height:4px;border-radius:2px;background:var(--kob-border-soft);margin:-6px 0 14px;overflow:hidden">
    <i style="display:block;height:100%;width:0;background:var(--kob-danger);transition:width .2s,background .2s"></i>
  </div>
  <div class="kob-row">
    <div class="kob-col-6"><input class="kob-combobox" name="building" data-options="label:'Building',labelPosition:'top',editable:false"></div>
    <div class="kob-col-6"><input class="kob-datebox"  name="moveIn"  data-options="label:'Move in',labelPosition:'top'"></div>
  </div>
  <input type="checkbox" class="kob-checkbox" name="terms" data-options="label:'I accept the terms'">
  <div style="display:flex;gap:8px;margin-top:16px">
    <a class="kob-linkbutton kob-linkbutton-primary icon-user-plus" id="rg-go"><span class="kob-icon"></span>Create account</a>
    <a class="kob-linkbutton icon-undo" id="rg-reset"><span class="kob-icon"></span>Reset</a>
  </div>
</form>
```

```js
Kob.combobox(root.querySelector('[name=building]'), {
  data: KOB_SAMPLE.buildings.map(function (b) { return { id: b, text: b }; })
});

var form = Kob.form(root.querySelector('#rg-form'));
var meter = root.querySelector('#rg-strength i');

// A password meter is a hint, not a gate: it never blocks the button.
root.querySelector('[name=pass]').addEventListener('input', function () {
  var v = this.value;
  var score = 0;
  if (v.length >= 8) { score++; }
  if (/[A-Z]/.test(v) && /[a-z]/.test(v)) { score++; }
  if (/[0-9]/.test(v)) { score++; }
  if (/[^A-Za-z0-9]/.test(v)) { score++; }
  meter.style.width = (score * 25) + '%';
  meter.style.background = score >= 4 ? 'var(--kob-success)'
    : score >= 2 ? 'var(--kob-warn)' : 'var(--kob-danger)';
});

root.querySelector('#rg-go').onclick = function () {
  if (!form.validate()) {
    return Kob.sweet.warn('Not quite', 'Some required fields are still empty.');
  }

  var v = form.read();
  if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(v.email)) {
    return Kob.sweet.error('Check the email', v.email + ' does not look like an address.');
  }
  if (v.pass !== v.pass2) {
    return Kob.sweet.error('Passwords differ', 'The two passwords are not the same.');
  }
  if (!v.terms) {
    return Kob.sweet.warn('One more thing', 'You have to accept the terms.');
  }

  Kob.sweet.success('Account created', v.first + ' ' + v.last + ' can sign in now.');
};

root.querySelector('#rg-reset').onclick = function () {
  form.clear();
  meter.style.width = '0';
};
```

**Example — Admin dashboard — full shell**

```html
<div class="kob-appshell" id="db-shell" style="height:640px;border:1px solid var(--kob-border);border-radius:12px">

  <header class="kob-appbar">
    <button class="kob-appbar-btn" id="db-rail" title="Collapse the sidebar"><span class="kob-icon icon-sidebar"></span></button>
    <span class="kob-appbar-brand"><span class="kob-appbar-mark">R</span>RentRoll</span>
    <span class="kob-sep"></span>
    <input class="kob-searchbox" id="db-find" style="width:230px" data-options="prompt:'Search room or tenant'">
    <span class="kob-spacer"></span>
    <button class="kob-appbar-btn" id="db-bell" title="Notifications">
      <span class="kob-icon icon-bell"></span><span class="kob-badge kob-badge-danger">3</span>
    </button>
    <button class="kob-appbar-btn" id="db-help" title="Help"><span class="kob-icon icon-question"></span></button>
    <span class="kob-sep"></span>
    <button class="kob-appbar-user" id="db-account">
      <span class="kob-avatar">SP</span>
      <span class="kob-appbar-user-lines">
        <span class="kob-appbar-user-name">Somchai P.</span>
        <span class="kob-appbar-user-role">Administrator</span>
      </span>
      <span class="kob-icon icon-chevron-down"></span>
    </button>
  </header>

  <nav class="kob-sidebar">
    <div class="kob-sidebar-title">Overview</div>
    <a class="kob-sidebar-item active" title="Dashboard"><span class="kob-icon icon-dashboard"></span><span class="kob-sidebar-label">Dashboard</span></a>
    <a class="kob-sidebar-item" title="Rent roll"><span class="kob-icon icon-table"></span><span class="kob-sidebar-label">Rent roll</span><span class="kob-badge kob-badge-accent">84</span></a>
    <a class="kob-sidebar-item" title="Invoices"><span class="kob-icon icon-invoice"></span><span class="kob-sidebar-label">Invoices</span><span class="kob-badge kob-badge-danger">28</span></a>
    <div class="kob-sidebar-title">Manage</div>
    <a class="kob-sidebar-item" title="Tenants"><span class="kob-icon icon-users"></span><span class="kob-sidebar-label">Tenants</span></a>
    <a class="kob-sidebar-item" title="Buildings"><span class="kob-icon icon-building"></span><span class="kob-sidebar-label">Buildings</span></a>
    <a class="kob-sidebar-item" title="Reports"><span class="kob-icon icon-chart-line"></span><span class="kob-sidebar-label">Reports</span></a>
    <a class="kob-sidebar-item" title="Settings"><span class="kob-icon icon-settings"></span><span class="kob-sidebar-label">Settings</span></a>
    <div class="kob-spacer"></div>
    <div class="kob-sidebar-sep"></div>
    <a class="kob-sidebar-item" title="Sign out"><span class="kob-icon icon-logout"></span><span class="kob-sidebar-label">Sign out</span></a>
  </nav>

  <main class="kob-appmain">
    <div class="kob-pagehead">
      <div>
        <div class="kob-crumbs"><span>RentRoll</span><span id="db-crumb">Dashboard</span></div>
        <h3 id="db-title">Dashboard</h3>
      </div>
      <div class="kob-spacer"></div>
      <a class="kob-linkbutton icon-download" id="db-export"><span class="kob-icon"></span>Export</a>
      <a class="kob-linkbutton kob-linkbutton-primary icon-add" id="db-new"><span class="kob-icon"></span>New invoice</a>
    </div>

    <div class="kob-autogrid kob-autogrid-sm" id="db-tiles" style="margin-bottom:14px"></div>

    <div class="kob-row">
      <div class="kob-col-7">
        <div class="kob-tabs" id="db-tabs" style="height:330px;border:1px solid var(--kob-border);border-radius:var(--kob-radius);overflow:hidden">
          <div title="Overdue first" data-options="iconCls:'icon-warn'"><div id="db-grid" style="height:100%"></div></div>
          <div title="By building"   data-options="iconCls:'icon-chart-pie'"><div id="db-bars" style="padding:16px"></div></div>
          <div title="Activity"      data-options="iconCls:'icon-history'"><div id="db-feed" style="padding:14px 16px"></div></div>
        </div>
      </div>
      <div class="kob-col-5">
        <div class="kob-panel" style="height:330px" data-options="title:'Month-end close',iconCls:'icon-list-check'">
          <div class="kob-stepper" id="db-steps" data-options="direction:'vertical',size:'sm'"></div>
          <div style="display:flex;gap:8px;margin-top:18px">
            <a class="kob-linkbutton icon-back" id="db-back"><span class="kob-icon"></span>Back</a>
            <a class="kob-linkbutton kob-linkbutton-primary icon-forward" id="db-fwd"><span class="kob-icon"></span>Next</a>
          </div>
        </div>
      </div>
    </div>
  </main>

  <div class="kob-statusbar kob-appfoot">
    <span class="kob-status-item kob-status-ok"><i class="kob-status-dot"></i>Live</span>
    <span class="kob-status-sep"></span>
    <span class="kob-status-item" id="db-count"></span>
    <span class="kob-spacer"></span>
    <span class="kob-status-item"><span class="kob-icon icon-clock"></span><span id="db-time"></span></span>
  </div>
</div>
```

```js
var rows = KOB_SAMPLE.rows(84);
var shell = root.querySelector('#db-shell');

function sum(list, field) {
  return list.reduce(function (n, r) { return n + r[field]; }, 0);
}
function count(status) {
  return rows.filter(function (r) { return r.status === status; }).length;
}

/* ---- the bar ---- */

// Collapsing the sidebar to a rail is one class on the shell; the
// stylesheet drops the labels and narrows the column.
root.querySelector('#db-rail').onclick = function () {
  shell.classList.toggle('kob-sidebar-collapsed');
};

var account = Kob.menu(document.createElement('div'), {
  items: [
    { text: 'Profile',     iconCls: 'icon-user' },
    { text: 'Preferences', iconCls: 'icon-sliders' },
    { separator: true },
    { text: 'Sign out',    iconCls: 'icon-logout' }
  ],
  onClick: function (item) { Kob.toast(item.text); }
});
root.querySelector('#db-account').onclick = function () { account.showFor(this); };

root.querySelector('#db-bell').onclick = function () {
  Kob.toast({ msg: '3 invoices went overdue today', type: 'warn' });
};
root.querySelector('#db-help').onclick = function () {
  Kob.sweet.info('Month-end close', 'Read the meters, issue, chase, then lock the month.');
};
root.querySelector('#db-export').onclick = function () { Kob.toast('Exporting 84 rows'); };
root.querySelector('#db-new').onclick = function () {
  Kob.toast({ msg: 'The invoice form would open here', type: 'info' });
};

/* ---- the sidebar ---- */

// Routing is the application's business — the shell only marks which
// entry is current and repaints the heading above the content.
var links = root.querySelectorAll('.kob-sidebar-item');
links.forEach(function (link) {
  link.onclick = function () {
    var name = link.getAttribute('title');
    if (name === 'Sign out') { Kob.toast('Signed out'); return; }
    links.forEach(function (other) { other.classList.remove('active'); });
    link.classList.add('active');
    root.querySelector('#db-title').textContent = name;
    root.querySelector('#db-crumb').textContent = name;
  };
});

/* ---- the tile row ---- */

var TILES = [
  { label: 'Billed this month', value: KOB_FMT.money(sum(rows, 'rent')), icon: 'icon-banknote', trend: 'up',   note: '+6.4% vs last month' },
  { label: 'Paid',              value: count('paid'),                    icon: 'icon-check-circle', tone: 'success' },
  { label: 'Overdue',           value: count('overdue'),                 icon: 'icon-warn',   tone: 'danger', trend: 'down', note: 'chase today' },
  { label: 'Occupied rooms',    value: rows.length + ' / 96',            icon: 'icon-building' }
];

root.querySelector('#db-tiles').innerHTML = TILES.map(function (t) {
  var tone = t.tone ? 'var(--kob-' + t.tone + ')' : 'var(--kob-accent)';
  return '<div class="kob-card"><div class="kob-card-body">' +
    '<div style="display:flex;align-items:center;gap:8px;color:var(--kob-muted);font-size:12.5px">' +
      '<span class="kob-icon ' + t.icon + '" style="color:' + tone + '"></span>' + t.label +
    '</div>' +
    '<div style="font-size:24px;font-weight:700;margin-top:6px">' + t.value + '</div>' +
    (t.note ? '<div style="display:flex;align-items:center;gap:4px;margin-top:4px;font-size:12px;color:' +
      (t.trend === 'down' ? 'var(--kob-danger)' : 'var(--kob-success)') + '">' +
      '<span class="kob-icon icon-trending-' + t.trend + '" style="width:13px;height:13px"></span>' + t.note + '</div>' : '') +
  '</div></div>';
}).join('');

/* ---- the grid, worst first ---- */

var tabs = Kob.tabs(root.querySelector('#db-tabs'));

var RANK = { overdue: 0, pending: 1, paid: 2 };
var grid = Kob.datagrid(root.querySelector('#db-grid'), {
  columns: [
    { field: 'room',   title: 'Room',   width: 80 },
    { field: 'tenant', title: 'Tenant', width: 130 },
    { field: 'rent',   title: 'Rent',   width: 100, align: 'right', formatter: KOB_FMT.money },
    { field: 'status', title: 'Status', width: 100, formatter: function (v) {
      return KOB_FMT.badge(v, v === 'paid' ? 'success' : v === 'overdue' ? 'danger' : 'warn');
    } }
  ],
  data: rows.slice().sort(function (a, b) { return RANK[a.status] - RANK[b.status]; }),
  filterable: false,
  pagination: false,
  fit: true
});

// The bar's search field drives the grid, and brings its tab forward
// so the result is not filtered away behind another page.
Kob.searchbox(root.querySelector('#db-find'), {
  delay: 200,
  onSearch: function (q) { grid.search(q); tabs.select(0); }
});

/* ---- a bar per building, drawn with two divs ---- */

var byBuilding = KOB_SAMPLE.buildings.map(function (name) {
  var mine = rows.filter(function (r) { return r.building === name; });
  return { name: name, total: sum(mine, 'rent'), rooms: mine.length };
});
var peak = Math.max.apply(null, byBuilding.map(function (b) { return b.total; }));

root.querySelector('#db-bars').innerHTML = byBuilding.map(function (b) {
  return '<div style="margin-bottom:14px">' +
    '<div style="display:flex;justify-content:space-between;font-size:13px;margin-bottom:5px">' +
      '<span>' + b.name + ' <span class="kob-muted">(' + b.rooms + ')</span></span>' +
      '<b>' + KOB_FMT.money(b.total) + '</b>' +
    '</div>' +
    '<div style="height:8px;border-radius:4px;background:var(--kob-border-soft);overflow:hidden">' +
      '<i style="display:block;height:100%;width:' + Math.round(b.total / peak * 100) + '%;background:var(--kob-accent)"></i>' +
    '</div></div>';
}).join('');

/* ---- what happened lately ---- */

var FEED = [
  { icon: 'icon-banknote',  tone: 'success', text: 'Tenant 12 paid 8,250.00',        when: '2 minutes ago' },
  { icon: 'icon-warn',      tone: 'danger',  text: 'Invoice 2026-0042 is overdue',   when: 'an hour ago' },
  { icon: 'icon-user-plus', tone: 'accent',  text: 'Tenant 85 moved into 118/2',     when: 'yesterday' },
  { icon: 'icon-file-text', tone: 'accent',  text: '28 invoices issued for the month', when: '2 days ago' }
];

root.querySelector('#db-feed').innerHTML = FEED.map(function (f) {
  return '<div style="display:flex;gap:10px;align-items:flex-start;padding:9px 0;border-bottom:1px solid var(--kob-border-soft)">' +
    '<span class="kob-icon ' + f.icon + '" style="margin-top:2px;color:var(--kob-' + f.tone + ')"></span>' +
    '<div style="flex:1;min-width:0"><div style="font-size:13.5px">' + f.text + '</div>' +
    '<div class="kob-muted" style="font-size:12px">' + f.when + '</div></div></div>';
}).join('');

/* ---- the checklist down the side ---- */

var steps = Kob.stepper(root.querySelector('#db-steps'), {
  steps: [
    { title: 'Read meters',    text: 'Water and electricity' },
    { title: 'Issue invoices', text: '84 rooms' },
    { title: 'Chase overdue',  text: count('overdue') + ' outstanding' },
    { title: 'Lock the month' }
  ],
  active: 1
});

root.querySelector('#db-back').onclick = function () { steps.prev(); };
root.querySelector('#db-fwd').onclick = function () {
  var last = steps.isLast();
  steps.next();
  if (last) { Kob.toast({ msg: 'The month is closed', type: 'success' }); }
};

/* ---- the status bar ---- */

root.querySelector('#db-count').innerHTML = '<b>' + rows.length + '</b> tenants · <b>' +
  count('overdue') + '</b> overdue';

var clock = root.querySelector('#db-time');
function tick() { clock.textContent = new Date().toLocaleTimeString(); }
tick();
setInterval(tick, 1000);
```

## Data

The grid, in the shapes it is usually needed in — including one with no actions column, where editing and deleting come from the row.

**Example — A grid in eight lines**

```html
<div class="ex-grid" style="height:330px"></div>
```

```js
Kob.datagrid(root.querySelector('.ex-grid'), {
  columns: [
    { field: 'room',     title: 'Room',     width: 90 },
    { field: 'tenant',   title: 'Tenant',   width: 160 },
    { field: 'building', title: 'Building', width: 130 },
    { field: 'rent',     title: 'Rent',     width: 110, align: 'right' }
  ],
  data: KOB_SAMPLE.rows(48)
});
```

**Example — Filters read what the reader sees**

```html
<div class="ex-grid" style="height:360px"></div>
<div style="display:flex;flex-wrap:wrap;gap:8px;margin-top:10px">
  <a class="kob-linkbutton icon-filter" id="ex-f-overdue"><span class="kob-icon"></span>Only overdue</a>
  <a class="kob-linkbutton icon-sum" id="ex-f-big"><span class="kob-icon"></span>Rent ≥ 8,000</a>
  <a class="kob-linkbutton icon-cancel" id="ex-f-clear"><span class="kob-icon"></span>Clear</a>
</div>
```

```js
var grid = Kob.datagrid(root.querySelector('.ex-grid'), {
  columns: [
    { field: 'room',     title: 'Room',     width: 90 },
    { field: 'tenant',   title: 'Tenant',   width: 150 },
    { field: 'building', title: 'Building', width: 120 },
    { field: 'rent',     title: 'Rent',     width: 110, align: 'right',
      formatter: KOB_FMT.money },
    { field: 'due',      title: 'Due',      width: 110 },
    // The cell renders a badge; the chip menu still offers
    // paid / pending / overdue, because filtering runs on the
    // text the formatter produced.
    { field: 'status',   title: 'Status',   width: 110,
      formatter: function (v) {
        return KOB_FMT.badge(v, v === 'paid' ? 'success'
          : v === 'overdue' ? 'danger' : 'warn');
      } },
    // 1 and 0 read as Yes and No, and filter that way too.
    { field: 'active',   title: 'Active',   width: 90, align: 'center',
      formatter: function (v) {
        return KOB_FMT.badge(v ? 'Yes' : 'No', v ? 'info' : 'muted');
      } }
  ],
  data: KOB_SAMPLE.rows(137),
  rownumbers: true,
  pageSize: 20
});

// The same filters the chips set, driven from your own toolbar.
root.querySelector('#ex-f-overdue').onclick = function () {
  grid.setFilter('status', { in: ['overdue'] });
};
root.querySelector('#ex-f-big').onclick = function () {
  grid.setFilter('rent', { ge: 8000 });
};
root.querySelector('#ex-f-clear').onclick = function () {
  grid.clearFilters();
};
```

**Example — Editing a row in place**

```html
<div class="ex-grid" style="height:300px"></div>
<p style="margin:10px 0 0;color:var(--kob-muted);font-size:13.5px">Double-click a row to edit it, then press Enter or use Save.</p>
```

```js
var editing = -1;

var grid = Kob.datagrid(root.querySelector('.ex-grid'), {
  columns: [
    { field: 'room',   title: 'Room',   width: 90 },
    { field: 'tenant', title: 'Tenant', width: 160, editor: 'text' },
    { field: 'rent',   title: 'Rent',   width: 120, align: 'right',
      formatter: KOB_FMT.money,
      editor: { type: 'numberbox', options: { precision: 2 } } }
  ],
  data: KOB_SAMPLE.rows(12),
  pagination: false,
  onDblClickRow: function (index) {
    if (editing >= 0) { grid.endEdit(editing); }
    editing = index;
    grid.beginEdit(index);
  },
  onEndEdit: function (index, row) {
    editing = -1;
    Kob.toast({ msg: 'Saved ' + row.room + ' — ' + KOB_FMT.money(row.rent), type: 'success' });
  }
});

root.addEventListener('keydown', function (e) {
  if (e.key === 'Enter' && editing >= 0) { grid.endEdit(editing); }
  if (e.key === 'Escape' && editing >= 0) { grid.cancelEdit(); editing = -1; }
});
```

**Example — Loading from an API**

```html
<div class="ex-grid" style="height:280px"></div>
```

```js
// Kob.config.request is the single place the library talks to a
// server. Replace it once and every widget follows — headers, an
// envelope to unwrap, a redirect on 401.
//
// Kob.config.request = function (url, params) {
//   return fetch(url + new URLSearchParams(params || {}), {
//     headers: { Authorization: 'Bearer ' + token }
//   }).then(function (res) {
//     if (res.status === 401) { location.href = '/login'; return []; }
//     return res.json();
//   }).then(function (payload) {
//     if (!payload.success) { throw new Error(payload.message); }
//     return payload.data;          // an array, or { rows, total }
//   });
// };

// Stubbed here so the page needs no backend of its own.
Kob.config.request = function () {
  return new Promise(function (resolve) {
    setTimeout(function () { resolve({ rows: KOB_SAMPLE.rows(60) }); }, 700);
  });
};

Kob.datagrid(root.querySelector('.ex-grid'), {
  columns: [
    { field: 'room',   title: 'Room',   width: 90 },
    { field: 'tenant', title: 'Tenant', width: 170 },
    { field: 'rent',   title: 'Rent',   width: 110, align: 'right', formatter: KOB_FMT.money }
  ],
  url: '/api/invoices',
  queryParams: { year: 2026 },
  pageSize: 20,
  onLoadSuccess: function () { Kob.toast({ msg: 'Loaded', type: 'info' }); }
});
```

**Example — Picking rows: checkboxes, Ctrl, Shift — and draggable columns**

```html
<p class="kob-muted" style="margin:0 0 10px;font-size:13.5px">
  Click a row, or its checkbox. <b>Ctrl</b> (<b>Cmd</b>) adds one, <b>Shift</b> takes the
  run from the last row you touched, and the box in the header ticks the whole page.
  Drag the edge of any header cell to resize that column.
</p>
<div class="kob-toolbar" style="border:1px solid var(--kob-border);border-bottom:none;border-radius:var(--kob-radius) var(--kob-radius) 0 0">
  <a class="kob-linkbutton icon-ok" id="ds-all"><span class="kob-icon"></span>Select all</a>
  <a class="kob-linkbutton icon-close" id="ds-none"><span class="kob-icon"></span>Clear</a>
  <span class="kob-sep"></span>
  <a class="kob-linkbutton kob-linkbutton-danger kob-linkbutton-soft icon-remove" id="ds-del"><span class="kob-icon"></span>Delete selected</a>
  <span class="kob-spacer"></span>
  <span id="ds-count" class="kob-muted" style="font-size:12.5px"></span>
</div>
<div id="ds-grid" style="height:330px"></div>
```

```js
var rows = KOB_SAMPLE.rows(60);

// checkbox:true turns multi-select on by itself — a column of
// checkboxes that only ever holds one tick is a radio button in the
// wrong clothes.
var grid = Kob.datagrid(root.querySelector('#ds-grid'), {
  columns: [
    { field: 'room',     title: 'Room',     width: 90 },
    { field: 'tenant',   title: 'Tenant',   width: 170 },
    { field: 'building', title: 'Building', width: 130 },
    { field: 'rent',     title: 'Rent',     width: 110, align: 'right', formatter: KOB_FMT.money },
    { field: 'status',   title: 'Status',   width: 110, resizable: false, formatter: function (v) {
        return KOB_FMT.badge(v, v === 'paid' ? 'success' : v === 'overdue' ? 'danger' : 'warn');
      } }
  ],
  data: rows,
  checkbox: true,
  pageSize: 8,
  filterable: false,
  fit: true,

  // One event for every way the selection can change — a click, a
  // checkbox, Shift over a run, or the header box.
  onSelectionChange: function (picked) { show(picked); }
});

var out = root.querySelector('#ds-count');

function show(picked) {
  if (!picked.length) { out.textContent = 'Nothing selected'; return; }
  var total = picked.reduce(function (n, r) { return n + r.rent; }, 0);
  out.innerHTML = '<b>' + picked.length + '</b> selected · ' + KOB_FMT.money(total);
}
show([]);

// The selection is kept as rows, not as highlighted <tr>s — so it
// survives paging, sorting and filtering, and selectAll() means every
// row the filters let through, not just the eight on screen.
root.querySelector('#ds-all').onclick = function () { grid.selectAll(); };
root.querySelector('#ds-none').onclick = function () { grid.unselectAll(); };

root.querySelector('#ds-del').onclick = function () {
  var picked = grid.getSelections();
  if (!picked.length) { return Kob.alert({ title: 'Nothing selected', msg: 'Tick a row first.' }); }
  Kob.confirm({ title: 'Delete', msg: 'Remove ' + picked.length + ' room(s)?' }).then(function (yes) {
    if (!yes) { return; }
    rows = rows.filter(function (r) { return picked.indexOf(r) === -1; });
    grid.loadData(rows);
    show([]);
    Kob.toast({ msg: 'Deleted ' + picked.length, type: 'warn' });
  });
};
```

**Example — Edit and delete from the row itself**

```html
<p class="kob-muted" style="margin:0 0 10px;font-size:13.5px">
  No actions column. Move the pointer over a row — or click one and use the keyboard.
  Double-clicking a row edits it too.
</p>
<div id="re-grid" style="height:280px"></div>
<p class="kob-muted" style="margin:10px 0 0;font-size:13.5px" id="re-out">nothing yet</p>
```

```js
var rows = KOB_SAMPLE.rows(40);
var out = root.querySelector('#re-out');

function edit(row) {
  Kob.prompt({ title: 'Rent for ' + row.room, msg: 'New amount', value: row.rent })
    .then(function (value) {
      if (value === null) { return; }
      row.rent = Number(value) || row.rent;
      grid.loadData(rows);
      out.textContent = row.room + ' set to ' + KOB_FMT.money(row.rent);
    });
}

function remove(row) {
  Kob.sweet({
    type: 'question',
    title: 'Delete ' + row.room + '?',
    msg: row.tenant + ' would lose the room.',
    showCancel: true, confirmText: 'Delete', danger: true
  }).then(function (yes) {
    if (!yes) { return; }
    rows.splice(rows.indexOf(row), 1);
    grid.loadData(rows);
    out.textContent = row.room + ' deleted';
  });
}

var grid = Kob.datagrid(root.querySelector('#re-grid'), {
  columns: [
    { field: 'room',     title: 'Room',     width: 90 },
    { field: 'tenant',   title: 'Tenant',   width: 150 },
    { field: 'building', title: 'Building', width: 130 },
    { field: 'rent',     title: 'Rent',     width: 110, align: 'right', formatter: KOB_FMT.money }
  ],
  data: rows,
  filterable: false,
  pageSize: 20,

  // One strip, moved to whichever row wants it. Nothing is added to the
  // columns, so the table is as wide as its data and no wider.
  rowActions: [
    { text: 'Edit', iconCls: 'icon-edit', handler: edit },
    {
      text: 'Delete', iconCls: 'icon-remove', color: 'danger',
      // A paid room is not deletable — the button says so rather than
      // letting the click through and failing afterwards.
      disabled: function (row) { return row.status === 'paid'; },
      handler: remove
    }
  ],

  onDblClickRow: function (i, row) { edit(row); }
});
```

## Forms

Labelled inputs, a value/text combobox, a calendar that speaks two eras, a debounced search field, a file drop zone, and one call to read or validate the lot.

**Example — Text, number and password**

```html
<form style="max-width:440px" onsubmit="return false">
  <input class="kob-textbox"     name="tenant" data-options="label:'Tenant',labelWidth:110,prompt:'Full name'">
  <input class="kob-numberbox"   name="rent"   data-options="label:'Rent',labelWidth:110,precision:2,min:0,groupSeparator:','">
  <input class="kob-passwordbox" name="pin" autocomplete="current-password" data-options="label:'PIN',labelWidth:110">
  <div style="text-align:right"><a class="kob-linkbutton icon-tip" id="ex-read"><span class="kob-icon"></span>Read values</a></div>
</form>
```

```js
var rent = Kob.numberbox(root.querySelector('.kob-numberbox'));
rent.setValue(12500);   // shown as 12,500.00, read back as a number

root.querySelector('#ex-read').onclick = function () {
  Kob.alert({
    title: 'Values',
    msg: 'tenant: ' + Kob.textbox(root.querySelector('.kob-textbox')).getValue() +
         '\nrent: ' + rent.getValue() + ' (' + typeof rent.getValue() + ')'
  });
};
```

**Example — Combobox**

```html
<div style="max-width:440px">
  <input class="kob-combobox" id="ex-cb-room" data-options="label:'Room',labelWidth:110,editable:false">
  <input class="kob-combobox" id="ex-cb-type" data-options="label:'Type',labelWidth:110,prompt:'type to filter'">
  <p style="margin:8px 0 0;color:var(--kob-muted);font-size:13.5px" id="ex-cb-out">nothing picked yet</p>
</div>
```

```js
var out = root.querySelector('#ex-cb-out');

// Pick from the list only — typing does not filter.
Kob.combobox(root.querySelector('#ex-cb-room'), {
  data: KOB_SAMPLE.rows(24).map(function (r) {
    return { id: r.id, text: r.room + ' — ' + r.tenant };
  }),
  value: 3,
  onChange: function (value, row) {
    out.textContent = 'value ' + value + '  ·  text "' + row.text + '"';
  }
});

// Editable: typing filters, and a formatter may return HTML.
Kob.combobox(root.querySelector('#ex-cb-type'), {
  valueField: 'code',
  textField: 'name',
  data: [
    { code: 'studio', name: 'Studio',    size: 24 },
    { code: '1br',    name: '1 bedroom', size: 32 },
    { code: '2br',    name: '2 bedroom', size: 48 },
    { code: 'duplex', name: 'Duplex',    size: 64 }
  ],
  formatter: function (row) {
    return row.name + ' <small style="color:var(--kob-muted)">' + row.size + ' m²</small>';
  }
});
```

**Example — Date picker and the Buddhist calendar**

```html
<div style="max-width:440px">
  <input class="kob-datebox" id="ex-date" data-options="label:'Move in',labelWidth:110">
  <div style="display:flex;gap:8px;margin-bottom:10px">
    <a class="kob-linkbutton" id="ex-en">English</a>
    <a class="kob-linkbutton" id="ex-th">ไทย (พ.ศ.)</a>
  </div>
  <p style="margin:0;color:var(--kob-muted);font-size:13.5px" id="ex-date-out"></p>
</div>
```

```js
var box = Kob.datebox(root.querySelector('#ex-date'), {
  value: '2026-03-09',
  onChange: report
});

function report() {
  root.querySelector('#ex-date-out').textContent =
    'on screen: ' + box.getText() + '   ·   getValue(): ' + box.getValue();
}

// The locale decides the display format and the era. The value the
// application reads is ISO yyyy-mm-dd either way.
function relocalise(name) {
  var iso = box.getValue();
  Kob.locale(name);
  box.setValue(iso);
  report();
}
root.querySelector('#ex-en').onclick = function () { relocalise('en'); };
root.querySelector('#ex-th').onclick = function () { relocalise('th'); };
report();
```

**Example — Checkbox switch**

```html
<div style="display:flex;flex-direction:column;gap:12px;max-width:380px">
  <input type="checkbox" class="kob-checkbox" data-options="label:'Tenant is active',checked:true">
  <input type="checkbox" class="kob-checkbox" id="ex-cb-mail" data-options="label:'Email the receipt'">
  <input type="checkbox" class="kob-checkbox" data-options="label:'Locked by the auditor',disabled:true,checked:true">
</div>
```

```js
// A real <input type="checkbox"> stays in the DOM, so forms submit it
// and getValue() is just its checked state.
Kob.checkbox(root.querySelector('#ex-cb-mail'), {
  onChange: function (checked) {
    Kob.toast({ msg: checked ? 'Receipt will be emailed' : 'No email', type: 'info' });
  }
});
```

**Example — Reading and validating a whole form**

```html
<form class="kob-form" id="ex-form" style="max-width:460px">
  <input class="kob-textbox"   name="tenant"  data-options="label:'Tenant',labelWidth:110,required:true">
  <input class="kob-combobox"  name="room"    id="ex-form-room" data-options="label:'Room',labelWidth:110,editable:false,required:true">
  <input class="kob-numberbox" name="rent"    data-options="label:'Rent',labelWidth:110,precision:2">
  <input class="kob-datebox"   name="moveIn"  data-options="label:'Move in',labelWidth:110">
  <input type="checkbox" class="kob-checkbox" name="active" data-options="label:'Active'">
  <div style="display:flex;gap:8px;justify-content:flex-end;margin-top:14px">
    <a class="kob-linkbutton icon-cancel" id="ex-form-clear"><span class="kob-icon"></span>Clear</a>
    <a class="kob-linkbutton icon-ok" id="ex-form-fill"><span class="kob-icon"></span>Fill</a>
    <a class="kob-linkbutton kob-linkbutton-primary icon-save" id="ex-form-save"><span class="kob-icon"></span>Save</a>
  </div>
</form>
<pre style="margin:12px 0 0;padding:10px 12px;border-radius:8px;background:var(--kob-accent-soft);font-size:12.5px" id="ex-form-out">values appear here</pre>
```

```js
Kob.combobox(root.querySelector('#ex-form-room'), {
  data: KOB_SAMPLE.rows(12).map(function (r) { return { id: r.room, text: r.room }; })
});

var form = Kob.form(root.querySelector('#ex-form'));
var out = root.querySelector('#ex-form-out');

// validate() marks every offender and focuses the first one.
root.querySelector('#ex-form-save').onclick = function () {
  out.textContent = form.validate()
    ? JSON.stringify(form.getValues(), null, 1)
    : 'Some required fields are still empty.';
};

root.querySelector('#ex-form-fill').onclick = function () {
  form.setValues({ tenant: 'Somchai P.', room: '104/5', rent: 8500, moveIn: '2026-04-01', active: true });
};
root.querySelector('#ex-form-clear').onclick = function () {
  form.clear();
  out.textContent = 'cleared';
};
```

**Example — Search box**

```html
<div style="display:flex;gap:10px;flex-wrap:wrap;align-items:center;margin-bottom:12px">
  <input class="kob-searchbox" id="sx-find" style="width:260px" data-options="prompt:'Room, tenant or building'">
  <span class="kob-muted" id="sx-out" style="font-size:13px"></span>
</div>
<div id="sx-grid" style="height:260px"></div>
```

```js
var rows = KOB_SAMPLE.rows(84);
var out = root.querySelector('#sx-out');

var grid = Kob.datagrid(root.querySelector('#sx-grid'), {
  columns: [
    { field: 'room',     title: 'Room',     width: 80 },
    { field: 'tenant',   title: 'Tenant',   width: 140 },
    { field: 'building', title: 'Building', width: 120 },
    { field: 'rent',     title: 'Rent',     width: 100, align: 'right', formatter: KOB_FMT.money }
  ],
  data: rows,
  filterable: false,
  searchable: false,
  pageSize: 20
});

// onSearch is debounced, so holding a key down costs one search, not
// twenty. Enter and the clear button skip the wait.
Kob.searchbox(root.querySelector('#sx-find'), {
  delay: 200,
  onSearch: function (q) {
    grid.search(q);
    out.textContent = q
      ? grid.getVisibleRows().length + ' of ' + rows.length + ' match “' + q + '”'
      : '';
  }
});
```

**Example — File upload**

```html
<div class="kob-row">
  <div class="kob-col-7">
    <div id="up-box"></div>
    <div style="display:flex;gap:8px;margin-top:12px">
      <a class="kob-linkbutton kob-linkbutton-primary icon-cloud-upload" id="up-send"><span class="kob-icon"></span>Upload</a>
      <a class="kob-linkbutton icon-remove" id="up-clear"><span class="kob-icon"></span>Clear</a>
    </div>
  </div>
  <div class="kob-col-5">
    <div class="kob-alert kob-alert-info" style="margin:0">
      <div class="kob-alert-title">This page has no server</div>
      <div class="kob-alert-body">Uploading really does POST to <code>/api/upload</code>, which is not there — so you get the progress bar and then the error state, both genuine.</div>
    </div>
    <pre id="up-out" style="margin-top:12px;font-size:12px;color:var(--kob-muted);white-space:pre-wrap"></pre>
  </div>
</div>
```

```js
var out = root.querySelector('#up-out');

var box = Kob.filebox(root.querySelector('#up-box'), {
  accept: '.pdf,.png,.jpg,.csv',
  maxSize: 2 * 1024 * 1024,
  maxFiles: 5,
  url: '/api/upload',
  fieldName: 'document',
  data: { tenantId: 42 },

  onAdd: function (file) { show(); },
  onRemove: function () { show(); },
  onProgress: function (file, percent) {
    out.textContent = file.name + ' — ' + percent + '%';
  },
  onError: function (file, why) {
    Kob.toast({ msg: file.name + ': ' + why, type: 'error' });
  },
  onComplete: function (ok, failed) {
    Kob.sweet[failed ? 'error' : 'success'](
      failed ? 'Upload failed' : 'Uploaded',
      ok + ' succeeded, ' + failed + ' failed.'
    );
    show();
  }
});

function show() {
  var files = box.getFiles();
  out.textContent = files.length
    ? files.map(function (f) { return f.name + '  (' + f.size + ' bytes)'; }).join('\n')
    : 'nothing queued';
}
show();

root.querySelector('#up-send').onclick = function () {
  if (!box.getFiles().length) {
    return Kob.sweet.warn('Nothing to upload', 'Add a file first.');
  }
  box.upload();
};

root.querySelector('#up-clear').onclick = function () { box.clear(); show(); };

// Leave 'url' out and the widget never touches the network: it just
// collects files, and box.getFiles() hands them to your own FormData.
```

## Containers and chrome

Panels, tabs, steppers, the layout frame, windows, and the message helpers.

**Example — Panel**

```html
<div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:14px">
  <div class="kob-panel" data-options="title:'Summary',iconCls:'icon-chart',collapsible:true">
    <p style="margin:0">Fold me away with the caret.</p>
  </div>
  <div class="kob-panel" id="ex-panel-load" data-options="title:'Loaded from a URL',iconCls:'icon-folder'">
  </div>
</div>
```

```js
// panel.load(url) drops the response HTML into the body and parses
// any widgets it contains. Here the markup is set directly instead,
// which goes through the same parsing step.
Kob.panel(root.querySelector('#ex-panel-load')).setContent(
  '<p style="margin-top:0">Content arrived, and the button below was ' +
  'parsed out of it.</p>' +
  '<a class="kob-linkbutton icon-reload"><span class="kob-icon"></span>Refresh</a>'
);
```

**Example — Tabs**

```html
<div class="kob-tabs" id="ex-tabs" style="height:190px;border:1px solid var(--kob-border);border-radius:10px;overflow:hidden">
  <div title="Details" style="padding:16px">Any direct child with a <code>title</code> becomes a page.</div>
  <div title="History" style="padding:16px" data-options="closable:true">This one can be closed.</div>
</div>
<div style="margin-top:10px"><a class="kob-linkbutton icon-add" id="ex-tab-add"><span class="kob-icon"></span>Add a tab</a></div>
```

```js
var tabs = Kob.tabs(root.querySelector('#ex-tabs'), {
  onSelect: function (index, title) { Kob.toast('Tab: ' + title); }
});

var n = 0;
root.querySelector('#ex-tab-add').onclick = function () {
  tabs.add({
    title: 'Note ' + (++n),
    content: '<div style="padding:16px">Added at ' + new Date().toLocaleTimeString() + '</div>',
    closable: true
  });
};
```

**Example — Stepper — across the page**

```html
<div class="kob-stepper" id="ex-stepper">
  <div title="Tenant" data-options="text:'Who is moving in',iconCls:'icon-user'">
    <form class="kob-form" id="ex-step-form" style="max-width:430px" onsubmit="return false">
      <input class="kob-textbox" name="tenant" data-options="label:'Full name',labelWidth:110,required:true">
      <input class="kob-textbox" name="phone"  data-options="label:'Phone',labelWidth:110">
    </form>
  </div>
  <div title="Room" data-options="text:'Which unit',iconCls:'icon-building'">
    <form class="kob-form" style="max-width:430px" onsubmit="return false">
      <input class="kob-combobox"  name="room" id="ex-step-room" data-options="label:'Room',labelWidth:110,editable:false">
      <input class="kob-numberbox" name="rent" data-options="label:'Rent',labelWidth:110,precision:2,groupSeparator:','">
    </form>
  </div>
  <div title="Confirm" data-options="text:'Check and sign',iconCls:'icon-clipboard'">
    <div class="kob-alert" style="max-width:430px" data-options="type:'info',title:'Ready to issue'">
      Nothing has been saved yet — the button below is what writes the lease.
    </div>
  </div>
</div>

<div style="display:flex;gap:8px;margin-top:18px">
  <a class="kob-linkbutton icon-back" id="ex-step-back"><span class="kob-icon"></span>Back</a>
  <a class="kob-linkbutton kob-linkbutton-primary icon-forward" id="ex-step-next"><span class="kob-icon"></span>Next</a>
  <span style="flex:1"></span>
  <a class="kob-linkbutton icon-reload" id="ex-step-reset"><span class="kob-icon"></span>Start over</a>
</div>
```

```js
// Each child with a title is both a step and the panel shown while
// that step is current — the same idiom as tabs.
var form = Kob.form(root.querySelector('#ex-step-form'));

// A list of objects is more than data-options can express, so the room
// list is handed over from here.
Kob.combobox(root.querySelector('#ex-step-room'), {
  data: [
    { id: '104/5', text: '104/5 — Sukhumvit' },
    { id: '118/2', text: '118/2 — Ratchada' },
    { id: '122/1', text: '122/1 — Thonglor' }
  ]
});

var back = Kob.linkbutton(root.querySelector('#ex-step-back'));
var next = Kob.linkbutton(root.querySelector('#ex-step-next'));

var wizard = Kob.stepper(root.querySelector('#ex-stepper'), {
  onChange: function () { sync(); },
  onFinish: function () {
    Kob.toast({ msg: 'Lease created', type: 'success' });
    sync();
  }
});

function sync() {
  if (wizard.isFirst()) { back.disable(); } else { back.enable(); }
  next.setText(wizard.isLast() ? 'Create the lease' : 'Next');
  next.setIcon(wizard.isLast() ? 'icon-check-circle' : 'icon-forward');
}
sync();

root.querySelector('#ex-step-back').onclick = function () { wizard.prev(); };

root.querySelector('#ex-step-next').onclick = function () {
  // A wizard has to be sure of the step it is leaving. error() paints
  // the marker red and leaves it that way until the page clears it.
  if (wizard.getActive() === 0 && !form.validate()) { wizard.error(); return; }
  wizard.setStatus(wizard.getActive(), null);
  wizard.next();
};

root.querySelector('#ex-step-reset').onclick = function () {
  form.clear();
  wizard.reset();
  sync();
};
```

**Example — Stepper — down the side**

```html
<div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(250px,1fr));gap:26px">
  <div>
    <p class="kob-muted" style="margin:0 0 14px;font-size:13px">Progress, with a line of detail under each step.</p>
    <div class="kob-stepper" id="ex-vstep" data-options="direction:'vertical'"></div>
    <div style="display:flex;gap:8px;margin-top:18px">
      <a class="kob-linkbutton icon-arrow-up" id="ex-vstep-prev"><span class="kob-icon"></span>Back</a>
      <a class="kob-linkbutton kob-linkbutton-primary icon-arrow-down" id="ex-vstep-next"><span class="kob-icon"></span>Advance</a>
      <a class="kob-linkbutton icon-warn" id="ex-vstep-fail"><span class="kob-icon"></span>Fail this step</a>
    </div>
  </div>
  <div>
    <p class="kob-muted" style="margin:0 0 14px;font-size:13px">Small, dotted markers — a status rail rather than a wizard.</p>
    <div class="kob-stepper" id="ex-vstep2" data-options="direction:'vertical',size:'sm',markers:'dot',clickable:false"></div>
  </div>
</div>
```

```js
// With no titled children the widget is the indicator on its own, and
// the steps come from the option instead.
var track = Kob.stepper(root.querySelector('#ex-vstep'), {
  steps: [
    { title: 'Order placed',  text: 'Paid by card' },
    { title: 'Packed',        text: 'Warehouse 2' },
    { title: 'On the way',    text: 'Courier collected it' },
    { title: 'Delivered',     text: 'Signed for at reception' }
  ],
  active: 2,
  onChange: function (i, was, step) { Kob.toast(step.title); }
});

root.querySelector('#ex-vstep-prev').onclick = function () { track.prev(); };
root.querySelector('#ex-vstep-next').onclick = function () { track.next(); };
root.querySelector('#ex-vstep-fail').onclick = function () { track.error(); };

// Every step here carries its own status, so nothing is derived from
// where the active one sits.
Kob.stepper(root.querySelector('#ex-vstep2'), {
  steps: [
    { title: 'Meters read',    text: '84 of 84',   status: 'done' },
    { title: 'Invoices sent',  text: '84 of 84',   status: 'done' },
    { title: 'Payments in',    text: '56 of 84',   status: 'active' },
    { title: 'Reminders',      text: 'blocked by 3 disputes', status: 'error' },
    { title: 'Month locked',   text: 'due on the 5th' }
  ]
});
```

**Example — Layout with a draggable splitter**

```html
<div class="kob-layout" id="ex-layout" style="height:260px;border:1px solid var(--kob-border);border-radius:10px;overflow:hidden">
  <div data-options="region:'north',height:56" style="padding:12px"><b>North</b> — fixed height</div>
  <div data-options="region:'west',width:180,split:true,minSize:120" style="padding:12px"><b>West</b><br>drag my right edge</div>
  <div data-options="region:'center'" style="padding:12px"><b>Center</b> — takes the rest</div>
  <div data-options="region:'south',height:48" style="padding:12px"><b>South</b></div>
</div>
<div style="margin-top:10px;display:flex;gap:8px">
  <a class="kob-linkbutton icon-chevron-left" id="ex-layout-fold"><span class="kob-icon"></span>Fold the west region</a>
</div>
```

```js
var layout = Kob.layout(root.querySelector('#ex-layout'));

root.querySelector('#ex-layout-fold').onclick = function () {
  layout.toggle('west');
};

// layout.panel('center') hands back the region element, so a datagrid
// or anything else can be mounted straight into it.
layout.panel('center').insertAdjacentHTML('beforeend',
  '<p style="color:var(--kob-muted);margin:8px 0 0;font-size:13.5px">' +
  'Regions are plain elements — put whatever you like inside.</p>');
```

**Example — Dialogs and windows**

```html
<div style="display:flex;flex-wrap:wrap;gap:8px">
  <a class="kob-linkbutton kob-linkbutton-primary icon-edit" id="ex-open-modal"><span class="kob-icon"></span>Modal dialog</a>
  <a class="kob-linkbutton icon-forward" id="ex-open-window"><span class="kob-icon"></span>Draggable window</a>
</div>

<div id="ex-modal" style="display:none">
  <form class="kob-form" id="ex-modal-form">
    <input class="kob-textbox" name="tenant" data-options="label:'Tenant',labelWidth:90,required:true">
    <input class="kob-numberbox" name="rent" data-options="label:'Rent',labelWidth:90,precision:2">
  </form>
</div>

<div id="ex-window" style="display:none">
  <p style="margin-top:0">Drag the header, pull any edge to resize, or use the corner buttons.</p>
  <div id="ex-window-grid" style="height:190px"></div>
</div>
```

```js
var form = Kob.form(root.querySelector('#ex-modal-form'));

var modal = Kob.dialog(root.querySelector('#ex-modal'), {
  title: 'Edit tenant',
  width: 420,
  buttons: [
    { text: 'Cancel', iconCls: 'icon-cancel', handler: function (d) { d.close(); } },
    { text: 'Save', iconCls: 'icon-save', primary: true, handler: function (d) {
        if (!form.validate()) { return; }
        Kob.toast({ msg: 'Saved ' + form.getValues().tenant, type: 'success' });
        d.close();
      } }
  ]
});

// modal:false turns the dialog into an application window: draggable,
// resizable, with minimise and maximise buttons.
var win = Kob.dialog(root.querySelector('#ex-window'), {
  title: 'Invoices', width: 560, height: 330, modal: false
});
Kob.datagrid(root.querySelector('#ex-window-grid'), {
  columns: [
    { field: 'room', title: 'Room', width: 90 },
    { field: 'tenant', title: 'Tenant', width: 150 },
    { field: 'rent', title: 'Rent', width: 110, align: 'right', formatter: KOB_FMT.money }
  ],
  data: KOB_SAMPLE.rows(30),
  pagination: false,
  filterable: false
});

root.querySelector('#ex-open-modal').onclick = function () { modal.open(); };
root.querySelector('#ex-open-window').onclick = function () { win.open(); };
```

**Example — Buttons and icons**

```html
<div style="display:flex;flex-wrap:wrap;gap:8px;align-items:center">
  <a class="kob-linkbutton kob-linkbutton-primary icon-save"><span class="kob-icon"></span>Save</a>
  <a class="kob-linkbutton icon-add">        <span class="kob-icon"></span>Add</a>
  <a class="kob-linkbutton icon-edit">       <span class="kob-icon"></span>Edit</a>
  <a class="kob-linkbutton icon-remove">     <span class="kob-icon"></span>Delete</a>
  <a class="kob-linkbutton icon-print" data-options="disabled:true"><span class="kob-icon"></span>Print</a>
  <a class="kob-linkbutton icon-filter" id="ex-toggle"><span class="kob-icon"></span>Filter</a>
</div>
```

```js
// Markup with a kob-* class is built by Kob.parse(). Reach an
// existing widget again by asking for it with no options.
Kob.linkbutton(root.querySelector('#ex-toggle'), {
  toggle: true,
  onClick: function () {
    Kob.toast('Filter ' + (Kob.linkbutton(this).isSelected() ? 'on' : 'off'));
  }
});
```

**Example — Button colours**

```html
<p class="kob-muted" style="margin:0 0 10px;font-size:13.5px">Solid — for the one action a screen is about.</p>
<div style="display:flex;flex-wrap:wrap;gap:8px;align-items:center;margin-bottom:20px">
  <a class="kob-linkbutton kob-linkbutton-accent icon-save"><span class="kob-icon"></span>Save</a>
  <a class="kob-linkbutton kob-linkbutton-success icon-check-circle"><span class="kob-icon"></span>Approve</a>
  <a class="kob-linkbutton kob-linkbutton-danger icon-remove"><span class="kob-icon"></span>Delete</a>
  <a class="kob-linkbutton kob-linkbutton-warn icon-warn"><span class="kob-icon"></span>Void</a>
  <a class="kob-linkbutton kob-linkbutton-info icon-send"><span class="kob-icon"></span>Send</a>
  <a class="kob-linkbutton"><span class="kob-icon icon-close"></span>Plain</a>
</div>
<p class="kob-muted" style="margin:0 0 10px;font-size:13.5px">Soft — the same meanings, for a toolbar that has several of them.</p>
<div style="display:flex;flex-wrap:wrap;gap:8px;align-items:center;margin-bottom:20px">
  <a class="kob-linkbutton kob-linkbutton-accent kob-linkbutton-soft icon-edit"><span class="kob-icon"></span>Edit</a>
  <a class="kob-linkbutton kob-linkbutton-success kob-linkbutton-soft icon-ok"><span class="kob-icon"></span>Mark paid</a>
  <a class="kob-linkbutton kob-linkbutton-danger kob-linkbutton-soft icon-remove"><span class="kob-icon"></span>Delete</a>
  <a class="kob-linkbutton kob-linkbutton-warn kob-linkbutton-soft icon-history"><span class="kob-icon"></span>Reverse</a>
  <a class="kob-linkbutton kob-linkbutton-info kob-linkbutton-soft icon-download"><span class="kob-icon"></span>Export</a>
</div>
<p class="kob-muted" style="margin:0 0 10px;font-size:13.5px">Built from JavaScript, and a plain <code>&lt;button class="kob-btn"&gt;</code>.</p>
<div style="display:flex;flex-wrap:wrap;gap:8px;align-items:center">
  <a class="kob-linkbutton" id="bc-js"></a>
  <a class="kob-linkbutton" id="bc-cycle"></a>
  <button class="kob-btn kob-btn-success">kob-btn-success</button>
  <button class="kob-btn kob-btn-danger">kob-btn-danger</button>
  <button class="kob-btn">kob-btn</button>
</div>
```

```js
// The class in the markup and the option are the same thing said two
// ways — Kob.parse reads one, this writes the other.
Kob.linkbutton(root.querySelector('#bc-js'), {
  text: 'From options',
  iconCls: 'icon-bolt',
  color: 'success'
});

var COLORS = ['accent', 'success', 'danger', 'warn', 'info'];
var at = 0;

var cycle = Kob.linkbutton(root.querySelector('#bc-cycle'), {
  text: 'color: accent',
  iconCls: 'icon-palette',
  color: 'accent',
  onClick: function () {
    at = (at + 1) % COLORS.length;
    cycle.option({ color: COLORS[at], text: 'color: ' + COLORS[at] });
  }
});

// The five come from --kob-<name>-solid and --kob-on-<name>, a pair per
// colour, so the label stays legible in all three themes. Try the theme
// switch at the top of the page.
```

**Example — Alerts, confirms, prompts and toasts**

```html
<div style="display:flex;flex-wrap:wrap;gap:8px;align-items:center">
  <a class="kob-linkbutton icon-tip" id="ex-m-alert"><span class="kob-icon"></span>Alert</a>
  <a class="kob-linkbutton icon-warn" id="ex-m-confirm"><span class="kob-icon"></span>Confirm</a>
  <a class="kob-linkbutton icon-edit" id="ex-m-prompt"><span class="kob-icon"></span>Prompt</a>
  <a class="kob-linkbutton icon-ok" id="ex-m-ok"><span class="kob-icon"></span>Success toast</a>
  <a class="kob-linkbutton icon-remove" id="ex-m-err"><span class="kob-icon"></span>Error toast</a>
</div>
<pre style="margin:12px 0 0;padding:10px 12px;border-radius:8px;background:var(--kob-accent-soft);font-size:12.5px" id="ex-m-out">the result of the last one shows here</pre>
```

```js
var out = root.querySelector('#ex-m-out');

// Each helper returns a promise, so it reads well with await too.
root.querySelector('#ex-m-alert').onclick = function () {
  Kob.alert({ title: 'Heads up', msg: 'Invoice 2026-0042 has been issued.' })
    .then(function (r) { out.textContent = 'alert resolved -> ' + r; });
};

root.querySelector('#ex-m-confirm').onclick = function () {
  Kob.confirm({ title: 'Delete', msg: 'Remove this tenant?' })
    .then(function (yes) { out.textContent = 'confirm resolved -> ' + yes; });
};

root.querySelector('#ex-m-prompt').onclick = function () {
  Kob.prompt({ title: 'Rename', msg: 'New room number:', value: '101/2' })
    .then(function (v) { out.textContent = 'prompt resolved -> ' + JSON.stringify(v); });
};

root.querySelector('#ex-m-ok').onclick = function () {
  Kob.toast({ msg: 'Saved successfully', type: 'success' });
};
root.querySelector('#ex-m-err').onclick = function () {
  Kob.toast({ msg: 'Could not reach the server', type: 'error' });
};
```

**Example — Big confirmations**

```html
<div style="display:flex;flex-wrap:wrap;gap:8px;align-items:center">
  <a class="kob-linkbutton icon-check-circle" data-sweet="success"><span class="kob-icon"></span>Success</a>
  <a class="kob-linkbutton icon-x-circle"     data-sweet="error"><span class="kob-icon"></span>Error</a>
  <a class="kob-linkbutton icon-warn"         data-sweet="warn"><span class="kob-icon"></span>Warning</a>
  <a class="kob-linkbutton icon-tip"          data-sweet="info"><span class="kob-icon"></span>Info</a>
  <a class="kob-linkbutton kob-linkbutton-primary icon-remove" id="sw-delete"><span class="kob-icon"></span>Delete a tenant</a>
  <a class="kob-linkbutton icon-clock" id="sw-timer"><span class="kob-icon"></span>Auto-close</a>
  <code class="kob-muted" id="sw-out" style="font-size:12.5px">answer appears here</code>
</div>
```

```js
var out = root.querySelector('#sw-out');

var COPY = {
  success: ['Saved', 'Invoice 2026-0042 has been issued.'],
  error:   ['Could not save', 'The server refused the invoice number.'],
  warn:    ['Check the dates', 'The move-out date is before the move-in date.'],
  info:    ['Scheduled', 'Rent reminders go out at 09:00 tomorrow.']
};

root.querySelectorAll('[data-sweet]').forEach(function (btn) {
  btn.onclick = function () {
    var type = btn.getAttribute('data-sweet');
    Kob.sweet[type](COPY[type][0], COPY[type][1]);
  };
});

// The destructive one asks, and says so in the button rather than
// making the reader work out which of OK / Cancel deletes.
root.querySelector('#sw-delete').onclick = function () {
  Kob.sweet({
    type: 'question',
    title: 'Delete Tenant 12?',
    msg: 'Room 112/3 becomes vacant. This cannot be undone.',
    showCancel: true,
    confirmText: 'Delete',
    cancelText: 'Keep',
    danger: true
  }).then(function (yes) {
    out.textContent = yes ? 'deleted' : 'kept';
    if (yes) { Kob.toast({ msg: 'Tenant 12 deleted', type: 'warn' }); }
  });
};

root.querySelector('#sw-timer').onclick = function () {
  Kob.sweet({ type: 'info', title: 'Closing in 2s', msg: 'timer: 2000', timer: 2000 });
};
```

## Navigation

Menus and a menu bar, a ribbon, a tree — and the whole windowed shell they were built for.

**Example — Desktop shell**

```html
<div class="kob-desktop" id="ex-desktop" style="height:520px;border:1px solid var(--kob-border);border-radius:12px;overflow:hidden"></div>
<p style="margin:10px 0 0;color:var(--kob-muted);font-size:13.5px">
  Double-click an icon, or use Start. Windows drag, resize, minimise to the taskbar and maximise.
</p>
```

```js
var money = KOB_FMT.money;

Kob.desktop(root.querySelector('#ex-desktop'), {
  user: { name: 'kob', onLogout: function () { Kob.toast('Logged out'); } },
  startExtras: [
    { text: 'Settings', iconCls: 'icon-settings' },
    { text: 'Log out',  iconCls: 'icon-back' }
  ],
  apps: [
    {
      id: 'rooms', title: 'Rooms', iconCls: 'icon-home', width: 640, height: 380,
      // Build the window contents yourself when it opens.
      onOpen: function (win, body) {
        var grid = document.createElement('div');
        grid.style.height = '100%';
        body.appendChild(grid);
        Kob.datagrid(grid, {
          columns: [
            { field: 'room',   title: 'Room',   width: 90 },
            { field: 'tenant', title: 'Tenant', width: 160 },
            { field: 'rent',   title: 'Rent',   width: 110, align: 'right', formatter: money }
          ],
          data: KOB_SAMPLE.rows(40),
          fit: true,
          filterable: false,
          pageSize: 20
        });
      }
    },
    {
      id: 'invoices', title: 'Invoices', iconCls: 'icon-file', width: 520, height: 320,
      content: '<div style="padding:18px"><h3 style="margin-top:0">Invoices</h3>' +
        '<p>Any HTML works as a window body. Widgets in it are parsed.</p>' +
        '<div class="kob-progressbar" data-options="value:64"></div></div>'
    },
    {
      id: 'chart', title: 'Reports', iconCls: 'icon-chart', width: 420, height: 260,
      content: '<div style="padding:18px"><div class="kob-alert" data-options="type:&#39;info&#39;">' +
        'Reports would render here.</div></div>'
    },
    { id: 'settings', title: 'Settings', iconCls: 'icon-settings', width: 380, height: 220,
      content: '<div style="padding:18px">Settings</div>' }
  ]
});
```

**Example — Ribbon**

```html
<div class="kob-ribbon" id="ex-ribbon" style="border:1px solid var(--kob-border);border-radius:10px;overflow:hidden"></div>
<p style="margin:10px 0 0;color:var(--kob-muted);font-size:13.5px" id="ex-ribbon-out">click a command</p>
```

```js
var out = root.querySelector('#ex-ribbon-out');

Kob.ribbon(root.querySelector('#ex-ribbon'), {
  tabs: [
    { title: 'Home', groups: [
      { title: 'Records', items: [
        { text: 'New',    iconCls: 'icon-add' },
        { text: 'Edit',   iconCls: 'icon-edit', size: 'small' },
        { text: 'Delete', iconCls: 'icon-remove', size: 'small' },
        { text: 'Copy',   iconCls: 'icon-copy', size: 'small' }
      ] },
      { title: 'Data', items: [
        { text: 'Refresh', iconCls: 'icon-reload' },
        // A button with `menu` opens one instead of firing.
        { text: 'Export',  iconCls: 'icon-download', menu: [
          { text: 'CSV', iconCls: 'icon-excel' },
          { text: 'PDF', iconCls: 'icon-file' }
        ] }
      ] },
      { title: 'Report', items: [{ text: 'Print', iconCls: 'icon-print' }] }
    ] },
    { title: 'View', groups: [
      { title: 'Layout', items: [
        { text: 'Rows',  iconCls: 'icon-menu' },
        { text: 'Cards', iconCls: 'icon-folder' }
      ] }
    ] },
    { title: 'Help', groups: [
      { title: 'Support', items: [{ text: 'About', iconCls: 'icon-tip' }] }
    ] }
  ],
  // Clicking the tab that is already open folds the ribbon away.
  onClick: function (item) { out.textContent = 'command: ' + item.text; }
});
```

**Example — Menu bar**

```html
<div class="kob-menubar" id="ex-menubar" style="border-radius:10px;border:1px solid var(--kob-border)"></div>
<p style="margin:10px 0 0;color:var(--kob-muted);font-size:13.5px" id="ex-mb-out">nothing chosen yet</p>
```

```js
var out = root.querySelector('#ex-mb-out');

Kob.menubar(root.querySelector('#ex-menubar'), {
  items: [
    { text: 'File', items: [
      { text: 'New tenant', iconCls: 'icon-add' },
      { text: 'Open',       iconCls: 'icon-folder' },
      { separator: true },
      { text: 'Print',      iconCls: 'icon-print', shortcut: 'Ctrl+P' }
    ] },
    { text: 'Edit', items: [
      { text: 'Undo', iconCls: 'icon-undo', shortcut: 'Ctrl+Z' },
      { text: 'Redo', iconCls: 'icon-redo', shortcut: 'Ctrl+Y' }
    ] },
    { text: 'View', items: [
      { text: 'Rows',    checked: true },
      { text: 'Cards' },
      { separator: true },
      { text: 'Refresh', iconCls: 'icon-reload' }
    ] },
    { text: 'Help', items: [{ text: 'About', iconCls: 'icon-tip' }] }
  ],
  // Once one menu is open, moving along the bar switches menus.
  onClick: function (item, top) {
    out.textContent = top.text + ' \u2192 ' + item.text;
  }
});
```

**Example — Menus and context menus**

```html
<div style="display:flex;flex-wrap:wrap;gap:8px;align-items:center">
  <a class="kob-linkbutton icon-menu" id="ex-menu-open"><span class="kob-icon"></span>Open a menu</a>
  <span style="color:var(--kob-muted);font-size:13.5px">…or right-click the panel below</span>
</div>
<div id="ex-menu-zone" style="margin-top:12px;padding:26px;border:1px dashed var(--kob-border);border-radius:10px;text-align:center;color:var(--kob-muted)">
  right-click here
</div>
<p style="margin:10px 0 0;color:var(--kob-muted);font-size:13.5px" id="ex-menu-out"></p>
```

```js
var out = root.querySelector('#ex-menu-out');

// A menu lives on its own element and floats — nothing is drawn
// where you build it.
var m = Kob.menu(document.createElement('div'), {
  items: [
    { text: 'New',  iconCls: 'icon-add',  shortcut: 'Ctrl+N' },
    { text: 'Open', iconCls: 'icon-folder', shortcut: 'Ctrl+O' },
    { separator: true },
    { text: 'Export', iconCls: 'icon-download', items: [
      { text: 'CSV',   iconCls: 'icon-excel' },
      { text: 'PDF',   iconCls: 'icon-file' },
      { text: 'Print', iconCls: 'icon-print' }
    ] },
    { separator: true },
    { text: 'Delete', iconCls: 'icon-remove', disabled: true }
  ],
  onClick: function (item) { out.textContent = 'picked: ' + item.text; }
});

root.querySelector('#ex-menu-open').onclick = function () {
  m.showFor(this);
};

// One call turns any element into a right-click surface.
m.bindContextMenu(root.querySelector('#ex-menu-zone'));
```

**Example — Row actions: a button and a right-click**

```html
<p class="kob-muted" style="margin:0 0 10px;font-size:13.5px">
  Use the <b>⋯</b> button on any row, or right-click the row — both open the same menu.
</p>
<div id="rm-grid" style="height:270px"></div>
<p class="kob-muted" style="margin:10px 0 0;font-size:13.5px" id="rm-out">no action yet</p>
```

```js
var rows = KOB_SAMPLE.rows(40);
var out = root.querySelector('#rm-out');
var target = null;

// One menu, reused for every row — building forty of them would be
// forty times the DOM for a thing only ever seen once at a time.
var menu = Kob.menu(document.createElement('div'), {
  items: [
    { text: 'Edit',          iconCls: 'icon-edit' },
    { text: 'Duplicate',     iconCls: 'icon-duplicate' },
    { text: 'Print invoice', iconCls: 'icon-print' },
    { separator: true },
    { text: 'Mark as paid',  iconCls: 'icon-check-circle' },
    { text: 'Send reminder', iconCls: 'icon-mail' },
    { separator: true },
    { text: 'Delete',        iconCls: 'icon-remove' }
  ],
  onClick: function (item) {
    if (!target) { return; }
    if (item.text === 'Delete') {
      return Kob.sweet({
        type: 'question', title: 'Delete ' + target.room + '?',
        showCancel: true, confirmText: 'Delete', danger: true
      }).then(function (yes) {
        out.textContent = yes ? 'deleted ' + target.room : 'kept ' + target.room;
      });
    }
    out.textContent = item.text + ' → ' + target.room + ' (' + target.tenant + ')';
  }
});

var grid = Kob.datagrid(root.querySelector('#rm-grid'), {
  columns: [
    { field: 'room',   title: 'Room',   width: 80 },
    { field: 'tenant', title: 'Tenant', width: 140 },
    { field: 'rent',   title: 'Rent',   width: 100, align: 'right', formatter: KOB_FMT.money },
    { field: 'id',     title: '',       width: 44, align: 'center',
      formatter: function () {
        return '<a class="kob-linkbutton kob-linkbutton-plain icon-more" data-row-menu' +
          ' title="Actions"><span class="kob-icon"></span></a>';
      } }
  ],
  data: rows,
  filterable: false,
  pageSize: 20,
  onClickRow: function (i, row) { target = row; }
});

// The buttons are drawn by a formatter, so there is nothing to bind
// to when the grid is built and nothing to rebind when it repages:
// one delegated listener on the grid covers every row forever.
root.querySelector('#rm-grid').addEventListener('click', function (e) {
  var button = e.target.closest('[data-row-menu]');
  if (!button) { return; }
  e.stopPropagation();
  var tr = button.closest('tr');
  target = grid.getVisibleRows()[Array.prototype.indexOf.call(tr.parentNode.children, tr)];
  menu.showFor(button);
});

// Right-click anywhere on a row opens the same menu at the pointer.
root.querySelector('#rm-grid').addEventListener('contextmenu', function (e) {
  var tr = e.target.closest('.kob-grid-body tbody tr');
  if (!tr) { return; }
  e.preventDefault();
  target = grid.getVisibleRows()[Array.prototype.indexOf.call(tr.parentNode.children, tr)];
  menu.showAt(e.clientX, e.clientY);
});
```

**Example — Tree**

```html
<div style="display:grid;grid-template-columns:minmax(0,1fr) minmax(0,1fr);gap:16px">
  <div>
    <div class="kob-tree" id="ex-tree" style="height:250px;border:1px solid var(--kob-border);border-radius:10px;padding:8px"></div>
    <div style="display:flex;gap:6px;margin-top:10px;flex-wrap:wrap">
      <a class="kob-linkbutton icon-chevron-down" id="ex-tree-all"><span class="kob-icon"></span>Expand all</a>
      <a class="kob-linkbutton icon-chevron-up" id="ex-tree-none"><span class="kob-icon"></span>Collapse all</a>
    </div>
  </div>
  <div>
    <div class="kob-tree" id="ex-tree-check" style="height:250px;border:1px solid var(--kob-border);border-radius:10px;padding:8px"></div>
    <p style="margin:10px 0 0;color:var(--kob-muted);font-size:13.5px" id="ex-tree-out">nothing ticked</p>
  </div>
</div>
```

```js
var data = [
  { id: 1, text: 'Sukhumvit', iconCls: 'icon-home', children: [
    { id: 11, text: 'Floor 1', children: [
      { id: 111, text: 'Room 101/2' },
      { id: 112, text: 'Room 102/3' }
    ] },
    { id: 12, text: 'Floor 2', children: [{ id: 121, text: 'Room 201/1' }] }
  ] },
  { id: 2, text: 'Ratchada', iconCls: 'icon-home', children: [
    { id: 21, text: 'Floor 1', children: [{ id: 211, text: 'Room 101/5' }] }
  ] }
];

var t = Kob.tree(root.querySelector('#ex-tree'), {
  data: JSON.parse(JSON.stringify(data)),
  lines: true,
  onSelect: function (node) { Kob.toast(node.text); }
});
root.querySelector('#ex-tree-all').onclick = function () { t.expandAll(); };
root.querySelector('#ex-tree-none').onclick = function () { t.collapseAll(); };

// With checkbox:true a folder ticks and unticks its children, and
// shows a dash while only some of them are ticked.
var out = root.querySelector('#ex-tree-out');
Kob.tree(root.querySelector('#ex-tree-check'), {
  data: JSON.parse(JSON.stringify(data)),
  checkbox: true,
  expandDepth: 2,
  onCheck: function () {
    var picked = Kob.instance(root.querySelector('#ex-tree-check'), 'tree').getChecked();
    out.textContent = picked.length
      ? picked.length + ' ticked: ' + picked.map(function (n) { return n.text; }).join(', ')
      : 'nothing ticked';
  }
});
```

## Feedback and layout

Progress, spinners, banners and badges — plus the cards, button groups and grid helpers that hold a screen together.

**Example — Progress and spinners**

```html
<div style="max-width:520px">
  <div class="kob-progressbar" id="ex-pb"></div>
  <div class="kob-progressbar" id="ex-pb-striped" style="margin-top:10px"></div>
  <div class="kob-progressbar" id="ex-pb-wait" style="margin-top:10px"></div>
  <div style="display:flex;gap:8px;margin-top:12px;flex-wrap:wrap;align-items:center">
    <a class="kob-linkbutton icon-forward" id="ex-pb-run"><span class="kob-icon"></span>Run a job</a>
    <a class="kob-linkbutton icon-reload" id="ex-pb-reset"><span class="kob-icon"></span>Reset</a>
    <span class="kob-spinner kob-spinner-sm"></span>
    <span class="kob-spinner kob-spinner-md"></span>
    <span class="kob-spinner kob-spinner-lg"></span>
  </div>
  <div id="ex-pre" style="position:relative;height:120px;margin-top:14px;border:1px solid var(--kob-border);border-radius:10px;padding:14px">
    <b>A panel that goes busy</b>
    <p style="margin:6px 0 0;color:var(--kob-muted);font-size:13.5px">Kob.loading() covers it and hands back the uncover function.</p>
  </div>
  <a class="kob-linkbutton icon-clock" id="ex-pre-go" style="margin-top:10px"><span class="kob-icon"></span>Cover it for 2s</a>
</div>
```

```js
var bar = Kob.progressbar(root.querySelector('#ex-pb'), {
  value: 35,
  onComplete: function () { Kob.toast({ msg: 'Finished', type: 'success' }); }
});
Kob.progressbar(root.querySelector('#ex-pb-striped'), {
  value: 70, type: 'warn', striped: true
});
// No total to measure against: a sweeping stripe instead of a fill.
Kob.progressbar(root.querySelector('#ex-pb-wait'), {
  indeterminate: true, type: 'success', height: 8
});

root.querySelector('#ex-pb-run').onclick = function () {
  var v = 0;
  var timer = setInterval(function () {
    v += 7;
    bar.setValue(v);
    if (v >= 100) { clearInterval(timer); }
  }, 120);
};
root.querySelector('#ex-pb-reset').onclick = function () { bar.setValue(0); };

root.querySelector('#ex-pre-go').onclick = function () {
  var done = Kob.loading(root.querySelector('#ex-pre'), 'Fetching invoices...');
  setTimeout(done, 2000);
};
```

**Example — Inline alerts and badges**

```html
<div style="max-width:620px">
  <div class="kob-alert" data-options="type:'info'">Rent for March has not been invoiced yet.</div>
  <div class="kob-alert" id="ex-alert-ok" data-options="type:'success',title:'Saved'">All 137 rows were written.</div>
  <div class="kob-alert" id="ex-alert-warn" data-options="type:'warn',title:'Check the meter readings',closable:true">
    Three rooms have a reading lower than last month.
  </div>
  <div class="kob-alert" id="ex-alert-danger" data-options="type:'danger',title:'Save failed',closable:true">
    The server refused the request.
  </div>

  <div style="display:flex;gap:10px;align-items:center;flex-wrap:wrap;margin-top:16px">
    <a class="kob-linkbutton icon-mail" id="ex-badge-btn"><span class="kob-icon"></span>Inbox <span class="kob-badge kob-badge-danger" id="ex-badge">3</span></a>
    <a class="kob-linkbutton icon-add" id="ex-badge-inc"><span class="kob-icon"></span>One more</a>
    <span class="kob-badge kob-badge-success">Paid</span>
    <span class="kob-badge kob-badge-warn">Pending</span>
    <span class="kob-badge kob-badge-danger">Overdue</span>
    <span class="kob-badge kob-badge-accent">New</span>
    <span class="kob-badge kob-badge-muted">Draft</span>
  </div>
</div>
```

```js
// Kob.alert() opens a modal. The inline banner is Kob.alertbox(),
// or class="kob-alert" picked up by the parser — as above.
var badge = Kob.badge(root.querySelector('#ex-badge'), { type: 'danger', max: 99 });
root.querySelector('#ex-badge-inc').onclick = function () { badge.increment(); };

// Built from script rather than markup, and dismissed after a while.
Kob.alertbox(root.querySelector('#ex-alert-ok')).setMessage('All 137 rows were written.');
```

**Example — Status bar**

```html
<div style="border:1px solid var(--kob-border);border-radius:var(--kob-radius);overflow:hidden">
  <div class="kob-toolbar" style="border-bottom:1px solid var(--kob-border)">
    <a class="kob-linkbutton icon-save" id="sb-save"><span class="kob-icon"></span>Save</a>
    <a class="kob-linkbutton icon-sync" id="sb-sync"><span class="kob-icon"></span>Sync</a>
    <a class="kob-linkbutton icon-ban" id="sb-break"><span class="kob-icon"></span>Break it</a>
  </div>
  <div id="sb-grid" style="height:210px"></div>
  <div class="kob-statusbar">
    <span class="kob-status-item" id="sb-state"><i class="kob-status-dot"></i><span>Ready</span></span>
    <span class="kob-status-sep"></span>
    <span class="kob-status-item"><span class="kob-icon icon-table"></span><span id="sb-rows"></span></span>
    <span class="kob-status-item"><span class="kob-icon icon-ok"></span><span id="sb-sel">no selection</span></span>
    <span class="kob-spacer"></span>
    <span class="kob-status-item"><span class="kob-icon icon-user"></span>admin</span>
    <span class="kob-status-sep"></span>
    <span class="kob-status-item" id="sb-saved">saved just now</span>
  </div>
</div>
```

```js
var rows = KOB_SAMPLE.rows(60);
var state = root.querySelector('#sb-state');

var grid = Kob.datagrid(root.querySelector('#sb-grid'), {
  columns: [
    { field: 'room',   title: 'Room',   width: 80 },
    { field: 'tenant', title: 'Tenant', width: 150 },
    { field: 'rent',   title: 'Rent',   width: 100, align: 'right', formatter: KOB_FMT.money }
  ],
  data: rows,
  filterable: false,
  pagination: false,
  fit: true,
  onClickRow: function (i, row) {
    root.querySelector('#sb-sel').textContent = row.room + ' selected';
  }
});

root.querySelector('#sb-rows').textContent = rows.length + ' rows';

// Three states, one element: the class carries the colour and the dot,
// the text says what it means. Colour alone would leave the state
// invisible to anyone who cannot separate green from amber.
function setState(kind, text) {
  state.className = 'kob-status-item kob-status-' + kind;
  state.lastChild.textContent = text;
}

root.querySelector('#sb-save').onclick = function () {
  setState('busy', 'Saving…');
  setTimeout(function () {
    setState('ok', 'Ready');
    root.querySelector('#sb-saved').textContent = 'saved at ' + new Date().toLocaleTimeString();
  }, 900);
};

root.querySelector('#sb-sync').onclick = function () {
  setState('busy', 'Syncing…');
  setTimeout(function () { setState('ok', 'Up to date'); }, 1200);
};

root.querySelector('#sb-break').onclick = function () {
  setState('bad', 'Connection lost');
};

setState('ok', 'Ready');
```

**Example — Filter buttons**

```html
<div style="display:flex;flex-wrap:wrap;gap:8px;align-items:center">
  <button class="kob-filterbutton" id="ex-f-building"></button>
  <button class="kob-filterbutton" id="ex-f-status"></button>
  <button class="kob-filterbutton" id="ex-f-rent"></button>
  <button class="kob-filterbutton" id="ex-f-name"></button>
  <a class="kob-linkbutton icon-cancel" id="ex-f-reset"><span class="kob-icon"></span>Reset</a>
</div>
<div class="ex-grid" style="height:280px;margin-top:12px"></div>
```

```js
var rows = KOB_SAMPLE.rows(137);

var grid = Kob.datagrid(root.querySelector('.ex-grid'), {
  columns: [
    { field: 'room',     title: 'Room',     width: 90 },
    { field: 'tenant',   title: 'Tenant',   width: 150 },
    { field: 'building', title: 'Building', width: 120 },
    { field: 'rent',     title: 'Rent',     width: 110, align: 'right', formatter: KOB_FMT.money },
    { field: 'status',   title: 'Status',   width: 110 }
  ],
  data: rows,
  filterable: false,          // the buttons above do the filtering
  pageSize: 20
});

// The chip from the grid's own toolbar, usable on its own — so a
// filter bar can live anywhere on the screen.
var filters = {};
function apply() {
  grid.loadData(rows.filter(function (r) {
    if (filters.building && filters.building.indexOf(r.building) === -1) { return false; }
    if (filters.status && filters.status.indexOf(r.status) === -1) { return false; }
    if (filters.rent !== undefined && filters.rent !== null && r.rent < filters.rent) { return false; }
    if (filters.tenant && r.tenant.toLowerCase().indexOf(filters.tenant.toLowerCase()) === -1) { return false; }
    return true;
  }));
}

Kob.filterbutton(root.querySelector('#ex-f-building'), {
  label: 'Building', options: KOB_SAMPLE.buildings,
  onChange: function (v) { filters.building = v; apply(); }
});
Kob.filterbutton(root.querySelector('#ex-f-status'), {
  label: 'Status', options: KOB_SAMPLE.statuses, multiple: false,
  onChange: function (v) { filters.status = v; apply(); }
});
Kob.filterbutton(root.querySelector('#ex-f-rent'), {
  label: 'Rent', kind: 'number',
  onChange: function (v) { filters.rent = v; apply(); }
});
Kob.filterbutton(root.querySelector('#ex-f-name'), {
  label: 'Tenant', kind: 'text',
  onChange: function (v) { filters.tenant = v; apply(); }
});

root.querySelector('#ex-f-reset').onclick = function () {
  ['building', 'status', 'rent', 'name'].forEach(function (key) {
    Kob.filterbutton(root.querySelector('#ex-f-' + key)).clear();
  });
  filters = {};
  apply();
};
```

**Example — Cards, button groups and the layout helpers**

```html
<div class="kob-autogrid" style="--kob-min:230px">
  <div class="kob-card kob-card-hover">
    <div class="kob-card-header"><span class="kob-icon icon-home"></span>Sukhumvit
      <div class="kob-card-tools"><span class="kob-badge kob-badge-success">92%</span></div>
    </div>
    <div class="kob-card-body">
      <p class="kob-muted kob-small kob-m-0">46 of 50 rooms occupied.</p>
      <div class="kob-progressbar" data-options="value:92,height:8" style="margin-top:10px"></div>
    </div>
    <div class="kob-card-footer">
      <span class="kob-muted kob-small">Updated today</span>
      <span class="kob-spacer"></span>
      <a class="kob-linkbutton icon-forward"><span class="kob-icon"></span>Open</a>
    </div>
  </div>

  <div class="kob-card">
    <div class="kob-card-header"><span class="kob-icon icon-chart"></span>This month</div>
    <div class="kob-card-body">
      <div class="kob-flex kob-items-baseline kob-gap-2">
        <b style="font-size:28px">฿418,500</b><span class="kob-badge kob-badge-success">+4.2%</span>
      </div>
      <p class="kob-muted kob-small kob-mt-2 kob-mb-0">Collected rent across three buildings.</p>
    </div>
  </div>

  <div class="kob-card">
    <div class="kob-card-header"><span class="kob-icon icon-warn"></span>Needs attention</div>
    <div class="kob-card-body">
      <div class="kob-alert" data-options="type:'warn'" style="margin:0">7 invoices are overdue.</div>
    </div>
  </div>
</div>

<h4 style="margin:22px 0 8px;font-size:14px">Button groups</h4>
<div class="kob-flex kob-items-center kob-gap-3 kob-flex-wrap">
  <div class="kob-btn-group" id="ex-bg">
    <button class="kob-btn selected">Rows</button>
    <button class="kob-btn">Cards</button>
    <button class="kob-btn">Chart</button>
  </div>
  <div class="kob-btn-group">
    <a class="kob-linkbutton icon-chevron-left"><span class="kob-icon"></span></a>
    <a class="kob-linkbutton icon-chevron-right"><span class="kob-icon"></span></a>
  </div>
</div>

<h4 style="margin:22px 0 8px;font-size:14px">The 12-column row</h4>
<div class="kob-row">
  <div class="kob-col-8"><div class="kob-card"><div class="kob-card-body">kob-col-8</div></div></div>
  <div class="kob-col-4"><div class="kob-card"><div class="kob-card-body">kob-col-4</div></div></div>
  <div class="kob-col-6"><div class="kob-card"><div class="kob-card-body">kob-col-6</div></div></div>
  <div class="kob-col-3"><div class="kob-card"><div class="kob-card-body">kob-col-3</div></div></div>
  <div class="kob-col-3"><div class="kob-card"><div class="kob-card-body">kob-col-3</div></div></div>
</div>
```

```js
// A button group behaves as a segmented control when you keep the
// selected class on one member.
var group = root.querySelector('#ex-bg');
group.addEventListener('click', function (e) {
  var btn = e.target.closest('.kob-btn');
  if (!btn) { return; }
  group.querySelectorAll('.kob-btn').forEach(function (b) { b.classList.remove('selected'); });
  btn.classList.add('selected');
  Kob.toast('View: ' + btn.textContent);
});

// Cards, alerts and the progress bar above came from markup —
// Kob.parse() built them before this script ran.
```

## Making it your own

Repaint it with CSS variables, or add a widget of your own that the markup parser treats exactly like a built-in.

**Example — Retheming with three variables**

```html
<div id="ex-theme" style="padding:18px;border-radius:12px;border:1px solid var(--kob-border)">
  <div style="display:flex;flex-wrap:wrap;gap:8px;margin-bottom:14px">
    <a class="kob-linkbutton kob-linkbutton-primary icon-save"><span class="kob-icon"></span>Save</a>
    <a class="kob-linkbutton icon-add"><span class="kob-icon"></span>Add</a>
    <input type="checkbox" class="kob-checkbox" data-options="label:'Active',checked:true">
  </div>
  <div class="ex-grid" style="height:190px"></div>
</div>
<div style="display:flex;flex-wrap:wrap;gap:8px;margin-top:12px">
  <a class="kob-linkbutton" data-accent="#17607a">Teal</a>
  <a class="kob-linkbutton" data-accent="#6d3bd4">Violet</a>
  <a class="kob-linkbutton" data-accent="#b3401f">Rust</a>
  <a class="kob-linkbutton" data-accent="#1c6b40">Forest</a>
</div>
```

```js
Kob.datagrid(root.querySelector('.ex-grid'), {
  columns: [
    { field: 'room',   title: 'Room',   width: 90 },
    { field: 'tenant', title: 'Tenant', width: 160 },
    { field: 'rent',   title: 'Rent',   width: 110, align: 'right', formatter: KOB_FMT.money }
  ],
  data: KOB_SAMPLE.rows(20),
  pagination: false,
  filterable: false
});

// Nothing in the stylesheet hard-codes a colour, so overriding the
// accent tokens on any element retheme everything inside it.
var scope = root.querySelector('#ex-theme');
root.querySelectorAll('[data-accent]').forEach(function (btn) {
  btn.onclick = function () {
    var accent = btn.getAttribute('data-accent');
    scope.style.setProperty('--kob-accent', accent);
    scope.style.setProperty('--kob-accent-dark', shade(accent, -0.25));
    scope.style.setProperty('--kob-accent-soft', accent + '18');
    scope.style.setProperty('--kob-accent-hover', accent + '2b');
  };
});

function shade(hex, amount) {
  var n = parseInt(hex.slice(1), 16);
  var c = [n >> 16, (n >> 8) & 255, n & 255].map(function (v) {
    return Math.max(0, Math.min(255, Math.round(v + v * amount)));
  });
  return 'rgb(' + c.join(',') + ')';
}
```

**Example — Writing your own widget**

```html
<div style="max-width:420px">
  <div class="kob-rating" data-options="value:3"></div>
  <p style="margin:10px 0 0;color:var(--kob-muted);font-size:13.5px" id="ex-rating-out"></p>
</div>
```

```js
// Extend Kob.Widget, register it, and Kob.parse() will build it from
// markup exactly like a built-in — data-options and all.
class Rating extends Kob.Widget {
  static widgetName = 'rating';
  static defaults = { max: 5, value: 0, onChange: null };

  init() {
    this.render();
    this.track(Kob.dom.on(this.el, 'click', '[data-n]', (e, star) => {
      this.setValue(Number(star.dataset.n));
    }));
  }

  setValue(v) {
    this.options.value = v;
    this.render();
    this.emit('onChange', v);
    return this;
  }

  getValue() { return this.options.value; }

  render() {
    var html = '';
    for (var n = 1; n <= this.options.max; n++) {
      html += '<span data-n="' + n + '" class="kob-icon icon-star" style="' +
        'cursor:pointer;width:22px;height:22px;color:' +
        (n <= this.options.value ? 'var(--kob-accent)' : 'var(--kob-border)') + '"></span>';
    }
    this.el.innerHTML = html;
  }
}

if (!Kob.registry.has('rating')) { Kob.rating = Kob.register(Rating); }

var out = root.querySelector('#ex-rating-out');
var widget = Kob.rating(root.querySelector('.kob-rating'), {
  onChange: function (v) { out.textContent = 'rated ' + v + ' / 5'; }
});
out.textContent = 'rated ' + widget.getValue() + ' / 5';
```

# TypeScript declarations

The contents of `types/index.d.ts` as published — every accessor, option
interface and method signature the library exposes.

```ts
/* Type definitions for kob-ui */

export as namespace Kob;

/** Anything a widget accessor will resolve to an element. */
export type Target = string | Element | ArrayLike<Element>;

export interface RequestConfig {
	/** Class prefix the markup parser looks for. Default 'kob-'. */
	prefix: string;
	/** Base z-index the floating-layer stack counts up from. Default 9100. */
	zIndex: number;
	/** Active locale name. Default 'en'. */
	locale: string;
	/**
	 * How combobox and datagrid fetch remote data. Replace to add auth headers,
	 * unwrap an envelope, or redirect on 401.
	 */
	request(url: string, params?: Record<string, unknown> | null): Promise<unknown>;
	/** Called when `request` rejects. */
	onRequestError(error: unknown, url: string): void;
}

export interface LocaleBundle {
	ok: string; cancel: string; close: string;
	minimize: string; maximize: string; restore: string;
	loading: string; loadingData: string;
	noData: string; noMatch: string;
	all: string; applyFilter: string; clear: string; clearFilters: string;
	searchAll: string; contains: string; atLeast: string; anyNumber: string;
	rowsPerPage: string; pageOf: string; showing: string;
	first: string; prev: string; next: string; last: string;
	today: string;
	months: string[];
	weekdaysShort: string[];
	/** 0 = Sunday. */
	firstDay: number;
	/** Display format built from yyyy / yy / mm / dd. */
	dateFormat: string;
	/** Show years in the Thai Buddhist era. */
	buddhistEra: boolean;
}

/* ------------------------------------------------------------------ base */

export interface WidgetOptions {
	[key: string]: unknown;
}

export class Widget<O extends WidgetOptions = WidgetOptions> {
	static widgetName: string;
	static defaults: WidgetOptions;
	readonly el: HTMLElement;
	readonly name: string;
	options: O;
	constructor(el: HTMLElement, options?: Partial<O>);
	init(): void;
	/** Merge in options and refresh; with no argument, returns the options. */
	option(patch?: Partial<O>): O;
	option(key: string): unknown;
	refresh(): void;
	destroy(): void;
}

/* ------------------------------------------------------------- form input */

export interface FieldOptions extends WidgetOptions {
	label?: string;
	labelWidth?: number;
	labelPosition?: 'left' | 'top' | '';
	prompt?: string;
	value?: unknown;
	readonly?: boolean;
	disabled?: boolean;
	required?: boolean;
	onChange?: (this: HTMLElement, value: unknown) => void;
}

export class TextBox<O extends FieldOptions = FieldOptions, V = string> extends Widget<O> {
	getValue(): V;
	setValue(v: unknown): this;
	getText(): string;
	clear(): this;
	enable(): this;
	disable(): this;
	readonly(mode?: boolean): this;
	focus(): this;
	isValid(): boolean;
}

export class PasswordBox extends TextBox {}

export interface NumberBoxOptions extends FieldOptions {
	min?: number;
	max?: number;
	/** Decimal places applied on blur. */
	precision?: number;
	/** Thousands separator shown while the field is not focused. */
	groupSeparator?: string;
}

export class NumberBox extends TextBox<NumberBoxOptions, number | ''> {
	normalize(keepEmpty?: boolean): this;
}

export interface ComboBoxOptions extends FieldOptions {
	data?: Record<string, unknown>[] | null;
	url?: string;
	queryParams?: Record<string, unknown> | null;
	valueField?: string;
	textField?: string;
	formatter?: (row: Record<string, unknown>) => string;
	/** false = pick from the list only. */
	editable?: boolean;
	panelHeight?: number;
	limit?: number;
	onSelect?: (this: HTMLElement, row: Record<string, unknown>) => void;
	onLoadSuccess?: (this: HTMLElement, rows: Record<string, unknown>[]) => void;
}

export class ComboBox extends Widget<ComboBoxOptions> {
	getValue(): unknown;
	setValue(v: unknown): this;
	getText(): string;
	loadData(rows: Record<string, unknown>[]): this;
	reload(url?: string): Promise<this>;
	getData(): Record<string, unknown>[];
	clear(): this;
	isValid(): boolean;
	enable(): this;
	disable(): this;
}

export interface DateBoxOptions extends FieldOptions {
	/** Overrides the locale's dateFormat for this field. */
	format?: string;
	/** ISO bounds, 'yyyy-mm-dd'. */
	min?: string;
	max?: string;
	showToday?: boolean;
	onSelect?: (this: HTMLElement, iso: string) => void;
}

export class DateBox extends Widget<DateBoxOptions> {
	/** ISO 'yyyy-mm-dd', or '' when empty. */
	getValue(): string;
	/** Accepts ISO, a Date, or a string in the display format. */
	setValue(v: string | Date | null): this;
	/** What the user sees, e.g. '09/03/2567'. */
	getText(): string;
	clear(): this;
	isValid(): boolean;
	enable(): this;
	disable(): this;
}

export interface CheckBoxOptions extends WidgetOptions {
	label?: string;
	checked?: boolean;
	disabled?: boolean;
	onChange?: (this: HTMLElement, checked: boolean) => void;
}

export class CheckBox extends Widget<CheckBoxOptions> {
	getValue(): boolean;
	setValue(v: boolean): this;
	check(): this;
	uncheck(): this;
	toggle(): this;
	enable(): this;
	disable(): this;
}

/* ---------------------------------------------------------------- button */

export type ButtonColor = 'accent' | 'success' | 'danger' | 'warn' | 'info';

export interface LinkButtonOptions extends WidgetOptions {
	text?: string;
	iconCls?: string;
	iconAlign?: 'left' | 'right';
	plain?: boolean;
	/** Shorthand for color: 'accent'. Superseded by `color` when both are set. */
	primary?: boolean;
	/** Paints the button. '' leaves it plain. */
	color?: '' | ButtonColor;
	/** The tonal version of `color`: tinted background, coloured label. */
	soft?: boolean;
	toggle?: boolean;
	selected?: boolean;
	disabled?: boolean;
	onClick?: (this: HTMLElement, event: MouseEvent) => void;
}

export class LinkButton extends Widget<LinkButtonOptions> {
	setText(text: string): this;
	getText(): string;
	setIcon(iconCls: string): this;
	toggle(on?: boolean): this;
	isSelected(): boolean;
	enable(): this;
	disable(): this;
}

/* ------------------------------------------------------------- searchbox */

export interface SearchBoxOptions extends FieldOptions {
	/** Milliseconds of quiet before onSearch fires. 0 fires on every keystroke. */
	delay?: number;
	/** Never search while typing — only on Enter or the clear button. */
	searchOnEnter?: boolean;
	/** Show the clear button once the field has a value. */
	clearable?: boolean;
	/** Receives the trimmed query. */
	onSearch?: (this: HTMLElement, query: string) => void;
	/** Fires when the field is emptied by the button or by Escape. */
	onClear?: (this: HTMLElement) => void;
}

export class SearchBox extends Widget<SearchBoxOptions> {
	/** The current query, trimmed. */
	getValue(): string;
	setValue(value: string): this;
	clear(): this;
	/** Run onSearch now, ignoring the debounce and the no-change guard. */
	search(value?: string): this;
	focus(): this;
}

/* --------------------------------------------------------------- filebox */

export type FileBoxStatus = 'ready' | 'uploading' | 'done' | 'error';

export interface FileBoxItem {
	file: File;
	status: FileBoxStatus;
	/** 0-100 while uploading. */
	percent: number;
	error: string;
}

export interface FileBoxOptions extends WidgetOptions {
	multiple?: boolean;
	/** Same syntax as the <input accept> attribute: '.pdf,image/*'. */
	accept?: string;
	/** Bytes. 0 means no limit. */
	maxSize?: number;
	/** How many files may be queued at once. 0 means no limit. */
	maxFiles?: number;
	/** Caption inside the drop zone. Falls back to the locale string. */
	text?: string;
	hint?: string;
	/** POST target. Leave empty and the widget never touches the network. */
	url?: string;
	/** Form field name each file is sent under. Default 'file'. */
	fieldName?: string;
	/** Extra form fields sent alongside every file. */
	data?: Record<string, string | Blob> | null;
	autoUpload?: boolean;
	headers?: Record<string, string> | null;
	disabled?: boolean;
	required?: boolean;
	onAdd?: (this: HTMLElement, file: File) => void;
	onRemove?: (this: HTMLElement, file: File) => void;
	onProgress?: (this: HTMLElement, file: File, percent: number) => void;
	onSuccess?: (this: HTMLElement, file: File, response: unknown) => void;
	onError?: (this: HTMLElement, file: File, message: string) => void;
	onComplete?: (this: HTMLElement, ok: number, failed: number) => void;
}

export class FileBox extends Widget<FileBoxOptions> {
	/** Queue files, dropping any that fail accept / maxSize / maxFiles. */
	add(files: FileList | File[]): this;
	remove(index: number): this;
	clear(): this;
	getFiles(): File[];
	getItems(): FileBoxItem[];
	isValid(): boolean;
	enable(): this;
	disable(): this;
	/** POST every queued file, one request each. Rejects when no url is set. */
	upload(): Promise<{ ok: number; failed: number }>;
}

/** "1.4 MB" — the same formatting the file list shows. */
export function formatSize(bytes: number): string;

/* ------------------------------------------------------------ containers */

export interface PanelOptions extends WidgetOptions {
	title?: string;
	iconCls?: string;
	fit?: boolean;
	border?: boolean;
	collapsible?: boolean;
	collapsed?: boolean;
	closable?: boolean;
	href?: string;
	loadingMessage?: string;
	onLoad?: (this: HTMLElement, body: HTMLElement) => void;
	onCollapse?: (this: HTMLElement) => void;
	onExpand?: (this: HTMLElement) => void;
	onClose?: (this: HTMLElement) => void;
}

export class Panel extends Widget<PanelOptions> {
	getBody(): HTMLElement;
	getHeader(): HTMLElement | null;
	setTitle(text: string): this;
	load(url?: string, done?: (body: HTMLElement) => void): Promise<this>;
	setContent(html: string): this;
	collapse(silent?: boolean): this;
	expand(silent?: boolean): this;
	toggleCollapse(): this;
	close(): this;
}

export type Region = 'north' | 'south' | 'west' | 'east' | 'center';

export interface LayoutOptions extends WidgetOptions {
	splitSize?: number;
	onCollapse?: (this: HTMLElement, region: Region) => void;
	onExpand?: (this: HTMLElement, region: Region) => void;
	onResize?: (this: HTMLElement, region: Region, size: number) => void;
}

export class Layout extends Widget<LayoutOptions> {
	panel(region: Region): HTMLElement | undefined;
	resize(region: Region, size: number): this;
	collapse(region: Region): this;
	expand(region: Region): this;
	toggle(region: Region): this;
	remove(region: Region): this;
}

export interface TabPage {
	el: HTMLElement;
	tab: HTMLElement;
	title: string;
	options: Record<string, unknown>;
}

export interface TabsOptions extends WidgetOptions {
	selected?: number;
	closable?: boolean;
	onSelect?: (this: HTMLElement, index: number, title: string) => void;
	onBeforeClose?: (this: HTMLElement, index: number, title: string) => boolean | void;
	onClose?: (this: HTMLElement, index: number, title: string) => void;
	onAdd?: (this: HTMLElement, title: string, el: HTMLElement) => void;
}

export class Tabs extends Widget<TabsOptions> {
	select(index: number): this;
	selectByTitle(title: string): this;
	getSelected(): TabPage | undefined;
	getPanel(index: number): HTMLElement | undefined;
	getPages(): TabPage[];
	add(spec: { title: string; content?: string; element?: HTMLElement; closable?: boolean; iconCls?: string; selected?: boolean }): TabPage;
	close(index: number): this;
}

/* --------------------------------------------------------------- stepper */

export type StepStatus = 'done' | 'active' | 'todo' | 'error';

export interface Step {
	title?: string;
	/** The line of explanation under the title. */
	text?: string;
	/** Replaces the number in the marker. */
	iconCls?: string;
	/** Pins a state on the step instead of deriving it from its position. */
	status?: StepStatus;
	[key: string]: unknown;
}

export interface StepperOptions extends WidgetOptions {
	/** Steps as data. Left out, the titled children are read instead. */
	steps?: (Step | string)[] | null;
	active?: number;
	direction?: 'horizontal' | 'vertical';
	size?: 'sm' | 'md';
	clickable?: boolean;
	/** Only steps already reached can be clicked. */
	linear?: boolean;
	markers?: 'number' | 'dot';
	doneIcon?: string;
	errorIcon?: string;
	onChange?: (this: HTMLElement, index: number, previous: number, step: Step) => void;
	onSelect?: (this: HTMLElement, index: number, step: Step) => void;
	onFinish?: (this: HTMLElement) => void;
}

export class Stepper extends Widget<StepperOptions> {
	go(index: number, silent?: boolean): this;
	next(): this;
	prev(): this;
	finish(): this;
	reset(): this;
	canReach(index: number): boolean;
	isFirst(): boolean;
	isLast(): boolean;
	isFinished(): boolean;
	getActive(): number;
	getStep(index?: number): Step | undefined;
	getSteps(): Step[];
	getPanel(index?: number): HTMLElement | undefined;
	setStatus(index: number, status: StepStatus | null): this;
	error(index?: number): this;
	setSteps(steps: (Step | string)[]): this;
}
/* ---------------------------------------------------------------- dialog */

export interface DialogButton {
	text: string;
	iconCls?: string;
	primary?: boolean;
	handler?: (this: HTMLElement, dialog: Dialog) => void;
}

export interface DialogOptions extends WidgetOptions {
	title?: string;
	width?: number;
	height?: number | 'auto';
	modal?: boolean;
	closed?: boolean;
	buttons?: DialogButton[] | null;
	draggable?: boolean;
	resizable?: boolean;
	minimizable?: boolean;
	maximizable?: boolean;
	/** Dock to the bottom edge instead of floating. */
	sheet?: boolean;
	minWidth?: number;
	minHeight?: number;
	onOpen?: (this: HTMLElement) => void;
	onClose?: (this: HTMLElement) => void;
	onResize?: (this: HTMLElement, box: { width: number; height: number }) => void;
	onMove?: (this: HTMLElement, box: { left: number; top: number }) => void;
	onMinimize?: (this: HTMLElement) => boolean | void;
	onMaximize?: (this: HTMLElement, maximized: boolean) => void;
}

export class Dialog extends Widget<DialogOptions> {
	open(): this;
	close(): this;
	isOpen(): boolean;
	minimize(): this;
	maximize(on?: boolean): this;
	restore(): this;
	isMaximized(): boolean;
	center(): this;
	setTitle(text: string): this;
	getTitle(): string;
	setButtons(buttons: DialogButton[] | null): this;
	resize(box: { width?: number; height?: number }): this;
	move(box: { left: number; top: number }): this;
	/** The outer .kob-window element. */
	window(): HTMLElement;
	getBody(): HTMLElement;
}

/* -------------------------------------------------------------- datagrid */

export type Row = Record<string, any>;

export interface Column {
	field?: string;
	title?: string;
	width?: number;
	align?: 'left' | 'center' | 'right';
	sortable?: boolean;
	/** false pins this column to its width when the others can be dragged. */
	resizable?: boolean;
	/** Render one cell. May return HTML. */
	formatter?: (value: any, row: Row, index: number) => string;
	/** Inline editor for this column. */
	editor?: 'text' | 'numberbox' | { type: 'text' | 'numberbox'; options?: { precision?: number } };
	/** false disables the filter chip; a string forces the chip kind. */
	filter?: false | 'text' | 'number' | 'enum' | 'bool';
}

export interface GridFilter {
	/** Substring match against the rendered cell text. */
	q?: string;
	/** Numeric lower bound. */
	ge?: number;
	/** Exact match against the raw field. */
	eq?: unknown;
	/** One of these rendered texts. */
	in?: string[];
}

export interface RowAction {
	/** Caption. Omit for an icon-only button, which takes its name from `title`. */
	text?: string;
	iconCls?: string;
	title?: string;
	color?: ButtonColor;
	/** Defaults to true — a strip of solid buttons over a row is too loud. */
	soft?: boolean;
	/** Re-evaluated for every row the strip lands on. */
	disabled?: boolean | ((this: HTMLElement, row: Row, index: number) => boolean);
	handler?: (this: HTMLElement, row: Row, index: number) => void;
}

export interface DataGridOptions extends WidgetOptions {
	columns?: Column[] | Column[][] | null;
	data?: Row[] | { rows: Row[] } | null;
	url?: string;
	queryParams?: Record<string, unknown> | null;
	loadFilter?: (payload: unknown) => unknown;
	idField?: string;
	pagination?: boolean;
	pageSize?: number;
	pageList?: number[];
	searchable?: boolean;
	filterable?: boolean;
	rownumbers?: boolean;
	showHeader?: boolean;
	striped?: boolean;
	singleSelect?: boolean;
	/** A leading column of checkboxes. Implies multi-select unless singleSelect is set. */
	checkbox?: boolean;
	/** Only the checkbox changes the selection; clicking the row does not. */
	selectOnCheckbox?: boolean;
	/** Drag the right edge of a header cell to resize that column. Default true. */
	resizable?: boolean;
	/** A column will not be dragged narrower than this. Default 48. */
	minColWidth?: number;
	fit?: boolean;
	emptyMsg?: string;
	onLoadSuccess?: (this: HTMLElement, data: unknown) => void;
	onLoadError?: (this: HTMLElement, error: unknown) => void;
	/** Actions shown over a row, for a grid with no column to spare. */
	rowActions?: RowAction[] | null;
	/** 'hover' — on hover and on the selected row. 'selected' — selection only. */
	rowActionsOn?: 'hover' | 'selected';
	onClickRow?: (this: HTMLElement, index: number, row: Row) => void;
	onDblClickRow?: (this: HTMLElement, index: number, row: Row) => void;
	onSelect?: (this: HTMLElement, index: number, row: Row) => void;
	onUnselect?: (this: HTMLElement, index: number, row: Row) => void;
	/** Every change to the selection, with the rows that are now selected. */
	onSelectionChange?: (this: HTMLElement, rows: Row[]) => void;
	onResizeColumn?: (this: HTMLElement, field: string, width: number) => void;
	onSortChange?: (this: HTMLElement, field: string, order: 'asc' | 'desc') => void;
	onFilterChange?: (this: HTMLElement, filters: Record<string, GridFilter>) => void;
	onEndEdit?: (this: HTMLElement, index: number, row: Row) => void;
}

export class DataGrid extends Widget<DataGridOptions> {
	readonly cols: Column[];
	loadData(payload: Row[] | { rows: Row[] } | { data: Row[] }): this;
	reload(arg?: string | { url: string; queryParams?: Record<string, unknown> }): Promise<this>;
	getRows(): Row[];
	getData(): Row[];
	getVisibleRows(): Row[];
	getRowByIndex(index: number): Row | undefined;
	getSelected(): Row | null;
	/** Every selected row, including ones on other pages. */
	getSelections(): Row[];
	getSelectionCount(): number;
	isSelected(row: Row): boolean;
	selectRow(index: number): this;
	unselectRow(index: number): this;
	/** Every row the filters let through, not only the page on screen. */
	selectAll(): this;
	unselectAll(): this;
	clearSelections(): this;
	sort(field: string, order?: 'asc' | 'desc'): this;
	setFilter(field: string, value: GridFilter | null): this;
	getFilters(): Record<string, GridFilter>;
	clearFilters(): this;
	search(text: string): this;
	gotoPage(n: number): this;
	pageCount(): number;
	loading(): this;
	loaded(): this;
	resize(): this;
	beginEdit(index: number): this;
	endEdit(index: number): this;
	cancelEdit(): this;
	refreshRow(index: number): this;
	/** The row's `<tr>`, if that row is on the page being shown. */
	rowElement(index: number): HTMLElement | null;
	/** Put the rowActions strip on a row; `hovering` paints it to match. */
	showRowActions(tr: HTMLElement, hovering?: boolean): this;
	hideRowActions(): this;
}

/* ------------------------------------------------------------------ form */

export interface FormOptions extends WidgetOptions {
	markInvalid?: boolean;
	onValidate?: (this: HTMLElement, ok: boolean, values: Record<string, unknown>) => boolean | void;
	onSubmit?: (this: HTMLElement, event: Event, values: Record<string, unknown>) => void;
}

export class Form extends Widget<FormOptions> {
	getValues(): Record<string, unknown>;
	setValues(values: Record<string, unknown>): this;
	clear(): this;
	validate(): boolean;
}

/* -------------------------------------------------------------- messager */

export interface MessageOptions {
	title?: string;
	msg?: string;
	/** Treat msg as HTML rather than text. */
	html?: boolean;
	icon?: 'info' | 'error' | 'warn';
	value?: string;
	fn?: (result: any) => void;
}

export interface ToastOptions {
	msg: string;
	type?: 'success' | 'error' | 'warn' | 'info';
	timeout?: number;
}

export interface ToastHandle {
	close(): void;
	element: HTMLElement;
}

export function alert(options: MessageOptions): Promise<true>;
export function alert(title: string, msg?: string, fn?: (r: true) => void): Promise<true>;
export function confirm(options: MessageOptions): Promise<boolean>;
export function confirm(title: string, msg?: string, fn?: (r: boolean) => void): Promise<boolean>;
export function prompt(options: MessageOptions): Promise<string | null>;
export function prompt(title: string, msg?: string, fn?: (r: string | null) => void): Promise<string | null>;
export function toast(options: ToastOptions | string): ToastHandle;

export const messager: {
	alert: typeof alert;
	confirm: typeof confirm;
	prompt: typeof prompt;
	toast: typeof toast;
	sweet: typeof sweet;
	show(options: MessageOptions & { buttons?: { text: string; primary?: boolean; result?: unknown }[]; input?: boolean }): Promise<any>;
};

/* ----------------------------------------------------------------- menu */

export interface MenuItem {
	text?: string;
	iconCls?: string;
	shortcut?: string;
	disabled?: boolean;
	checked?: boolean;
	separator?: boolean;
	items?: MenuItem[];
	onClick?: (this: HTMLElement, item: MenuItem) => void;
	[key: string]: unknown;
}

export interface MenuOptions extends WidgetOptions {
	items?: MenuItem[];
	minWidth?: number;
	onClick?: (this: HTMLElement, item: MenuItem) => void;
	onShow?: (this: HTMLElement) => void;
	onHide?: (this: HTMLElement) => void;
}

export class Menu extends Widget<MenuOptions> {
	showFor(anchor: Element, place?: { side?: 'right'; gap?: number }): this;
	showAt(x: number, y: number): this;
	/** Right-click inside `target` opens this menu at the pointer. */
	bindContextMenu(target: Element | Document): this;
	hide(): this;
	isOpen(): boolean;
	setItems(items: MenuItem[]): this;
	panel(): HTMLElement;
}

export interface MenuBarOptions extends WidgetOptions {
	items?: { text?: string; iconCls?: string; items?: MenuItem[] }[];
	onClick?: (this: HTMLElement, item: MenuItem, top: unknown) => void;
}

export class MenuBar extends Widget<MenuBarOptions> {
	openMenu(index: number): this;
	closeMenu(): this;
	getMenu(index: number): Menu | undefined;
	setItems(items: MenuBarOptions['items']): this;
}

/* ----------------------------------------------------------------- tree */

export interface TreeNode {
	id?: string | number;
	text?: string;
	iconCls?: string;
	children?: TreeNode[];
	state?: 'open' | 'closed';
	checked?: boolean;
	[key: string]: any;
}

export interface TreeOptions extends WidgetOptions {
	data?: TreeNode[] | null;
	url?: string;
	queryParams?: Record<string, unknown> | null;
	idField?: string;
	textField?: string;
	childrenField?: string;
	checkbox?: boolean;
	cascadeCheck?: boolean;
	lines?: boolean;
	expandDepth?: number;
	formatter?: (node: TreeNode) => string;
	onClick?: (this: HTMLElement, node: TreeNode) => void;
	onDblClick?: (this: HTMLElement, node: TreeNode) => void;
	onSelect?: (this: HTMLElement, node: TreeNode) => void;
	onExpand?: (this: HTMLElement, node: TreeNode) => void;
	onCollapse?: (this: HTMLElement, node: TreeNode) => void;
	onCheck?: (this: HTMLElement, node: TreeNode, checked: boolean) => void;
	onLoadSuccess?: (this: HTMLElement, nodes: TreeNode[]) => void;
	onContextMenu?: (this: HTMLElement, event: MouseEvent, node: TreeNode) => void;
}

export class Tree extends Widget<TreeOptions> {
	loadData(data: TreeNode[] | { rows: TreeNode[] }): this;
	reload(url?: string): Promise<this>;
	expand(node: TreeNode): Promise<this>;
	collapse(node: TreeNode): this;
	toggle(node: TreeNode): this | Promise<this>;
	expandAll(): this;
	collapseAll(): this;
	select(node: TreeNode | null): this;
	getSelected(): TreeNode | null;
	find(id: string | number): TreeNode | null;
	check(node: TreeNode, on?: boolean): this;
	getChecked(): TreeNode[];
	walk(nodes: TreeNode[], fn: (node: TreeNode) => void): this;
	getData(): TreeNode[];
}

/* --------------------------------------------------------------- ribbon */

export interface RibbonItem {
	text?: string;
	iconCls?: string;
	size?: 'large' | 'small';
	disabled?: boolean;
	menu?: MenuItem[];
	onClick?: (this: HTMLElement, item: RibbonItem) => void;
}

export interface RibbonTab {
	title?: string;
	groups?: { title?: string; items?: RibbonItem[] }[];
}

export interface RibbonOptions extends WidgetOptions {
	tabs?: RibbonTab[];
	selected?: number;
	collapsible?: boolean;
	collapsed?: boolean;
	onSelect?: (this: HTMLElement, index: number, tab: RibbonTab) => void;
	onClick?: (this: HTMLElement, item: RibbonItem | MenuItem, parent?: RibbonItem) => void;
}

export class Ribbon extends Widget<RibbonOptions> {
	select(index: number): this;
	collapse(): this;
	expand(): this;
	toggleCollapse(): this;
	setTabs(tabs: RibbonTab[]): this;
}

/* ------------------------------------------------- progress, preloader */

export interface ProgressBarOptions extends WidgetOptions {
	value?: number;
	indeterminate?: boolean;
	text?: string | false;
	height?: number;
	type?: 'accent' | 'success' | 'warn' | 'danger';
	striped?: boolean;
	onChange?: (this: HTMLElement, value: number, previous: number) => void;
	onComplete?: (this: HTMLElement) => void;
}

export class ProgressBar extends Widget<ProgressBarOptions> {
	setValue(value: number): this;
	getValue(): number;
	indeterminate(on?: boolean): this;
}

export interface PreloaderOptions extends WidgetOptions {
	msg?: string;
	size?: 'sm' | 'md' | 'lg';
	visible?: boolean;
	backdrop?: boolean;
	timeout?: number;
	onShow?: (this: HTMLElement) => void;
	onHide?: (this: HTMLElement) => void;
}

export class Preloader extends Widget<PreloaderOptions> {
	show(msg?: string): this;
	hide(): this;
	isVisible(): boolean;
	setMessage(msg: string): this;
}

/** Cover something while work happens; the returned function uncovers it. */
export function loading(target: Target, msg?: string): () => void;

/* ------------------------------------------------------- alert, badge */

export interface AlertOptions extends WidgetOptions {
	type?: 'info' | 'success' | 'warn' | 'danger';
	title?: string;
	msg?: string;
	html?: boolean;
	iconCls?: string | false;
	closable?: boolean;
	timeout?: number;
	onClose?: (this: HTMLElement) => void;
}

/** The inline banner. `Kob.alert()` is the modal dialog. */
export class Alert extends Widget<AlertOptions> {
	setMessage(msg: string): this;
	setType(type: AlertOptions['type']): this;
	close(): this;
}

export interface BadgeOptions extends WidgetOptions {
	text?: string | number;
	type?: 'muted' | 'accent' | 'success' | 'warn' | 'danger' | 'info';
	dot?: boolean;
	max?: number;
	hideEmpty?: boolean;
}

export class Badge extends Widget<BadgeOptions> {
	setText(text: string | number): this;
	getText(): string;
	setType(type: BadgeOptions['type']): this;
	increment(by?: number): this;
}

/* -------------------------------------------------------- filterbutton */

export interface FilterButtonOptions extends WidgetOptions {
	label?: string;
	kind?: 'enum' | 'text' | 'number';
	options?: (string | { value: string | number; text?: string })[];
	value?: string[] | string | number | null;
	multiple?: boolean;
	clearText?: string | false;
	onChange?: (this: HTMLElement, value: string[] | string | number | null) => void;
}

export class FilterButton extends Widget<FilterButtonOptions> {
	getValue(): string[] | string | number | null;
	setValue(value: string[] | string | number | null): this;
	clear(): this;
	setOptions(options: FilterButtonOptions['options']): this;
}

/* ------------------------------------------------------------- desktop */

export interface DesktopApp {
	id: string;
	title?: string;
	iconCls?: string;
	/** Image URL, used instead of iconCls. */
	icon?: string;
	/** Fetch this fragment into the window. */
	href?: string;
	/** Or set the window body's HTML directly. */
	content?: string;
	width?: number;
	height?: number;
	/** false allows more than one window of this app. */
	single?: boolean;
	hidden?: boolean;
	onOpen?: (this: HTMLElement, win: Dialog, body: HTMLElement) => void;
}

export interface DesktopOptions extends WidgetOptions {
	apps?: DesktopApp[];
	icons?: boolean;
	taskbar?: boolean;
	startLabel?: string | false;
	startExtras?: MenuItem[];
	clock?: boolean;
	user?: { name?: string; iconCls?: string; onLogout?: (this: HTMLElement) => void };
	wallpaper?: string;
	onOpen?: (this: HTMLElement, app: DesktopApp, win: Dialog) => void;
	onClose?: (this: HTMLElement, app: DesktopApp) => void;
	onFocus?: (this: HTMLElement, app: DesktopApp, win: Dialog) => void;
}

export class Desktop extends Widget<DesktopOptions> {
	/** Launch an app, or focus the window it already has. */
	open(id: string): Dialog | null;
	close(app: string | object): this;
	closeAll(): this;
	minimize(id: string): this;
	getRunning(): { app: DesktopApp; win: Dialog }[];
	getWindow(id: string): Dialog | undefined;
	setApps(apps: DesktopApp[]): this;
	setWallpaper(value: string): this;
}

/* ----------------------------------------------------------------- popup */

export interface Popup {
	el: HTMLElement;
	isOpen(): boolean;
	open(): Popup;
	close(): Popup;
	showFor(anchor: Element, place?: { side?: 'right'; gap?: number }): Popup;
	showAt(x: number, y: number): Popup;
	destroy(): void;
}

export function createPopup(options?: { className?: string; onClose?: () => void }): Popup;
export function closeAllPopups(): void;

/* --------------------------------------------------------------- factory */

/** Create the widget, or return the existing one; passing options updates it. */
export interface WidgetFactory<W, O> {
	(target: Target, options?: Partial<O>): W;
	Widget: new (el: HTMLElement, options?: Partial<O>) => W;
	defaults: O;
}

export const textbox: WidgetFactory<TextBox, FieldOptions>;
export const passwordbox: WidgetFactory<PasswordBox, FieldOptions>;
export const numberbox: WidgetFactory<NumberBox, NumberBoxOptions>;
export const combobox: WidgetFactory<ComboBox, ComboBoxOptions>;
export const datebox: WidgetFactory<DateBox, DateBoxOptions>;
export const checkbox: WidgetFactory<CheckBox, CheckBoxOptions>;
export const searchbox: WidgetFactory<SearchBox, SearchBoxOptions>;
export const filebox: WidgetFactory<FileBox, FileBoxOptions>;
export const linkbutton: WidgetFactory<LinkButton, LinkButtonOptions>;
export const panel: WidgetFactory<Panel, PanelOptions>;
export const layout: WidgetFactory<Layout, LayoutOptions>;
export const tabs: WidgetFactory<Tabs, TabsOptions>;
export const stepper: WidgetFactory<Stepper, StepperOptions>;
export const dialog: WidgetFactory<Dialog, DialogOptions>;
export const datagrid: WidgetFactory<DataGrid, DataGridOptions>;
export const form: WidgetFactory<Form, FormOptions>;

export const menu: WidgetFactory<Menu, MenuOptions>;
export const menubar: WidgetFactory<MenuBar, MenuBarOptions>;
export const tree: WidgetFactory<Tree, TreeOptions>;
export const ribbon: WidgetFactory<Ribbon, RibbonOptions>;
export const progressbar: WidgetFactory<ProgressBar, ProgressBarOptions>;
export const preloader: WidgetFactory<Preloader, PreloaderOptions>;
export const badge: WidgetFactory<Badge, BadgeOptions>;
export const filterbutton: WidgetFactory<FilterButton, FilterButtonOptions>;
export const desktop: WidgetFactory<Desktop, DesktopOptions>;
/** The inline banner widget. Kob.alert() is the modal dialog. */
export const alertbox: WidgetFactory<Alert, AlertOptions>;

export type SweetType = 'success' | 'error' | 'warn' | 'info' | 'question';

export interface SweetOptions {
	type?: SweetType | '';
	title?: string;
	msg?: string;
	/** Treat msg as markup. Only pass markup you produced yourself. */
	html?: boolean;
	confirmText?: string;
	cancelText?: string;
	showCancel?: boolean;
	/** Paint the confirm button as destructive. */
	danger?: boolean;
	/** Auto-dismiss after n milliseconds, resolving false. */
	timer?: number;
	closeOnBackdrop?: boolean;
	fn?: (answer: boolean) => void;
}

export interface Sweet {
	/**
	 * The big centred confirmation. Resolves true for confirm and false for
	 * cancel, Escape, backdrop or timer — so `if (await Kob.sweet(…))` is
	 * always safe to write.
	 */
	(options: SweetOptions | string): Promise<boolean>;
	success(title: string | SweetOptions, msg?: string): Promise<boolean>;
	error(title: string | SweetOptions, msg?: string): Promise<boolean>;
	warn(title: string | SweetOptions, msg?: string): Promise<boolean>;
	info(title: string | SweetOptions, msg?: string): Promise<boolean>;
	question(title: string | SweetOptions, msg?: string): Promise<boolean>;
}

export const sweet: Sweet;

/** dialog() with modal forced on. */
export function modal(target: Target, options?: Partial<DialogOptions>): Dialog;
/** dialog() with modal forced off — a draggable application window. */
export function windowed(target: Target, options?: Partial<DialogOptions>): Dialog;

/* ----------------------------------------------------------------- misc */

export const version: string;
export const config: RequestConfig;
export const locales: Record<string, LocaleBundle>;

/** Build every widget declared in the markup under `root`. */
export function parse(root?: Element | Document): Widget[];
/** Destroy every widget under `root`. */
export function unparse(root?: Element | Document): void;
/** parse(document) now, or as soon as the document is ready. */
export function autoParse(): void;
/** Read the inline data-options syntax. */
export function parseOptions(str: string): Record<string, unknown>;

/** Switch locale, or read the current one. */
export function locale(name?: string): string;
/** Register a locale; missing keys fall back to English. */
export function addLocale(name: string, bundle: Partial<LocaleBundle>): LocaleBundle;
/** Look up a locale string, interpolating {placeholders}. */
export function t(key: string, vars?: Record<string, unknown>): string;
/** Next z-index for a floating layer. */
export function zIndex(): number;

/** The widget of that name living on an element, if any. */
export function getInstance(el: Element, name: string): Widget | undefined;
/** Register your own widget class. */
export function register<W extends Widget, O extends WidgetOptions>(
	klass: new (el: HTMLElement, options?: Partial<O>) => W
): WidgetFactory<W, O>;
export const registry: Map<string, typeof Widget>;

declare const Kob: {
	version: string;
	textbox: typeof textbox;
	passwordbox: typeof passwordbox;
	numberbox: typeof numberbox;
	combobox: typeof combobox;
	datebox: typeof datebox;
	checkbox: typeof checkbox;
	searchbox: typeof searchbox;
	filebox: typeof filebox;
	linkbutton: typeof linkbutton;
	panel: typeof panel;
	layout: typeof layout;
	tabs: typeof tabs;
	stepper: typeof stepper;
	dialog: typeof dialog;
	datagrid: typeof datagrid;
	form: typeof form;
	menu: typeof menu;
	menubar: typeof menubar;
	tree: typeof tree;
	ribbon: typeof ribbon;
	progressbar: typeof progressbar;
	preloader: typeof preloader;
	loading: typeof loading;
	badge: typeof badge;
	filterbutton: typeof filterbutton;
	desktop: typeof desktop;
	alertbox: typeof alertbox;
	modal: typeof modal;
	window: typeof windowed;
	popup: typeof createPopup;
	closePopups: typeof closeAllPopups;
	messager: typeof messager;
	alert: typeof alert;
	confirm: typeof confirm;
	prompt: typeof prompt;
	toast: typeof toast;
	parse: typeof parse;
	unparse: typeof unparse;
	autoParse: typeof autoParse;
	parseOptions: typeof parseOptions;
	config: RequestConfig;
	locale: typeof locale;
	addLocale: typeof addLocale;
	locales: typeof locales;
	t: typeof t;
	zIndex: typeof zIndex;
	Widget: typeof Widget;
	register: typeof register;
	registry: typeof registry;
	instance: typeof getInstance;
	dom: Record<string, Function>;
	date: Record<string, Function>;
	classes: Record<string, typeof Widget>;
};

export default Kob;
```

<!-- kob-ui v0.2.3 — generated by scripts/build-llms.mjs; do not edit by hand -->