# smartwebUI

> A dependency-free component library where semantic HTML is the public API and AI agents are first-class citizens. Components are hand-writable HTML enhanced by a small JS runtime; a machine-readable catalog (smartwebui.catalog.json) lets agents render validated, safe surfaces declaratively. Browser support: releases from the preceding 36 months only — no legacy bundles, no polyfills.

License: smartwebUI Source License v1.0 — © 2026 Elonovo. Free to use and customize for your own projects; redistributing modified or rebranded versions requires written permission. See LICENSE.md.

## Documentation

- [Getting started, theming, utilities, browser policy](https://www.smartwebui.dev/docs.php)
- [Design choices & tradeoffs, FAQ, comparison](https://www.smartwebui.dev/docs.php#design-choices)
- [Agent security & e-commerce scope](https://www.smartwebui.dev/docs.php#agent-security)
- [Component reference (38 HTML families; catalog is 34 types + 4 primitives)](https://www.smartwebui.dev/docs.php#components)
- [Design tokens](https://www.smartwebui.dev/docs.php#tokens)
- [Agent contract and declarative surfaces](https://www.smartwebui.dev/docs.php#agent)
- [Changelog](https://www.smartwebui.dev/changelog.php)
- [Live showcase](https://www.smartwebui.dev/demo.php)

## Install

No build step. Copy `smartwebui.css` and `smartwebui.js` (optionally `smartwebui-agent.js` + `smartwebui.catalog.json` for agent surfaces, `smartwebui-stripe.js` for payments):

```html
<link rel="stylesheet" href="/assets/smartwebui.css">
<script defer src="/assets/smartwebui.js"></script>
```

## Core conventions for agents generating markup

- Every component is plain HTML with `smart-*` classes and `data-smart-*` behavior attributes. Hydration is automatic on DOMContentLoaded and after `SmartWebUI.update()`/`render()`/`patch()`.
- Interactive controls keep a native hidden input (`input[type=hidden]`) in sync, so ordinary form posts work unchanged.
- The `hidden` attribute is the primary visibility mechanism; `SmartWebUI.hide()` / `SmartWebUI.show()` manage it. Visibility utilities: `.smart-hidden`, `.smart-invisible`, `.smart-hidden-mobile`, `.smart-visible-mobile`.
- Spacing/typography/layout utilities: `.smart-p-*` / `.smart-m-*` / `.smart-gap-*` (0–8, token-referenced; logical `pt/pb/ps/pe` and `mt/mb/ms/me`; `mx/my` axes), `.smart-text-*`, `.smart-grid--2/3/4`, `.smart-span-2/full`, desktop spans, `.smart-container--sm/md/lg`, `.smart-ratio-*`, `.smart-elevated-*`, `.smart-rounded-*`, `.smart-divider`, `.smart-kbd`, `.smart-line-clamp-2/3/4`, `.smart-sticky(-top)`, `.smart-z-raised/sticky/tooltip/toast/banner`, tablet/desktop visibility, `.smart-reveal`, `.smart-skip-link` (focus-revealed bypass link to `#main`).
- Validation is native: `:user-invalid`/`:user-valid` are styled, `required` adds a marker, `.smart-error--live` reveals on failure; server errors use `.smart-field--invalid` + `.smart-error`. For JS-driven flows, `SmartWebUI.validate(form, rules, { summary })` wires `aria-invalid`, error messages, and a FormErrors summary.
- 1.0.2 components: vertical tabs (`.smart-tabs--vertical` + `aria-orientation="vertical"`, Up/Down keys), split button (`.smart-split-button` wrapping two `.smart-button`s + popover menu), quantity stepper (`.smart-quantity` with `[data-smart-step]` buttons + number input, `Field control: "quantity"`), password strength (`input[data-smart-strength]` auto-creates the meter), dropzone file upload (`.smart-file[data-smart-dropzone]`, `data-max-size` + `accept` validation, `SmartWebUI.upload(input, url, options)` with `smart:upload-*` progress events), OTP verification (`.smart-otp` digit row — auto-advance, paste distribution, `smart:otp` events, `Field control: "otp"` with `length`), countdown (`SmartWebUI.countdown(el, seconds, { warnBelow, onExpire })` or `data-smart-countdown` markup, `smart:countdown` events).
- 1.1 application kit: AppHeader + nested AppShell + Footer and the Alert consent placement; sticky/expandable/width-controlled/totals tables and page size; Field multi-select/numeric-range/rating/color/mask variations plus icon adornments and textarea counters; placed Toasts; collapsing Breadcrumbs; connectivity and scroll-to-top affordances; CommandPalette + shortcuts; Avatar groups/status, List timeline/key-value/notification/attachment variations, Progress ring/bar/spinner/skeleton variations, and the Carousel family (snap strip, gallery grid, zoomable lightbox viewer).
- 1.2 collaborative HTML: `data-smart-richtext` sanitizes toolbar HTML before hydrating the editor or writing the hidden form field (default tags: p, br, strong, b, em, i, u, ul, ol, li, a; subset with `data-smart-richtext-allow`); emits `smart:change` with `{ value, control }`; `data-smart-board` uses Enter/Space to lift, arrows to preview, Enter/Space to drop (Escape cancels), plus pointer/touch drag, emitting `smart:board` and `smart:move`; `data-smart-composer` auto-resizes and emits `smart:send`.
- Page-header toolbar: apply `smart-page-header--toolbar` to a `smart-page-header` and wrap its related filters, search, or view controls in `smart-page-header__toolbar`. The toolbar stays compact and inline from tablet widths upward, then wraps on smaller screens.
- Print: `.smart-no-print` hides chrome on paper; `.smart-print-document` is a flattened, print-optimized document surface for invoices and receipts.
- Scroll panes: `.smart-scroll-y` / `.smart-scroll-x` (thin scrollbars, contained overscroll), `.smart-pane-fill` / `-tall` / `-screen` (`--smart-pane-offset` subtracts chrome height) for messenger-style layouts.
- Chrome strings (placeholders, aria labels, validation messages) localize through `SmartWebUI.setLocale({ key: "…" })`; dates and currency always use `Intl`.
- All spacing/borders/radii are logical properties — set `dir="rtl"` and the interface mirrors.
- Use sprite SVGs, not Unicode glyphs, for interface actions and status marks. Icon-only controls require a textual accessible name; their SVG stays decorative. Keep prose punctuation, keyboard characters, and mathematical notation as text.
- Opt in to the unsupported-browser banner with `<html data-smart-compat>`.

## Agent runtime (smartwebui-agent.js)

- Protocol: `smartwebui.surface/1.0`. Surfaces are JSON: `{ surface: string, root: { type, id, children? } }`.
- 38 catalog types — 34 component types plus 4 layout primitives: Stack, Cluster, Grid, Text, Icon, Button, Field, Choice, Switch, SegmentedControl, Card, Badge, Tabs, Accordion, Dialog, Drawer, PopoverMenu, Tooltip, Toast, Progress, Alert, Breadcrumbs, Pagination, Table, Empty, Avatar, List, Chip, PageHeader, AppShell, AppHeader, Footer, CommandPalette, FormErrors, Stepper, Payment, Chart, Carousel. Universal property: `hidden` (boolean). This catalog list is not the same as the 38 HTML families in the component reference (those count Combobox, File, Date/time, Search, Tags, and Confirm separately, and do not number Icon).
- Carousel nodes browse media: `items[]` carry `src` (surface src policy), `alt`, `caption`, and optional nested `content` nodes rendered over the media. `variant` is `carousel` (snap strip with dots and arrows) or `gallery` (grid of zoom-trigger cells); `ratio` is `1x1` | `4x3` | `16x9` | `21x9`. `autoplay` pauses on hover, focus, and offscreen and never starts under `prefers-reduced-motion`. `lightbox: true` opens a native-dialog viewer with swipe, drag-to-dismiss, and pinch/double-tap/⌘-scroll/keyboard zoom. `smart:slide` carries `{ index }`; snapshots expose `selected`. At most 24 items.
- Icons use names from `smartwebui-icons.json`; authored SVG points to `smartwebui-icons.svg#smart-icon-{name}`. Size is any CSS length through `--smart-icon-size`; stroke uses `--smart-icon-stroke`. Give standalone meaningful icons a label and leave decorative icons hidden from assistive technology. `loadIconCatalog()` pins the runtime sprite and catalog URLs to the loaded payload (`?v=version.count`) so a cached sprite can never lag a fresh catalog; call `setIconSource(spriteUrl, catalogUrl)` first when you host the sprite elsewhere.
- Chart nodes plot finite numeric series as `sparkline`, `bar`, `line`, `area`, or `donut`. Tones are `accent` | `success` | `warning` | `danger` | `secondary` only. Do not emit SVG, hex colors, or path data. Sparkline belongs inside a metric `Card`.
- The renderer never accepts HTML, scripts, classes, or inline styles from agent JSON. Unknown properties fail closed. `href`/`src` are restricted to http(s), mailto, relative paths, and in-page hashes. Depth, node-count, and text-length limits apply.
- API: `SmartWebUI.render(target, surface)`, `SmartWebUI.patch(target, ops)` (`data.patch`, `node.upsert`, `node.remove`, `node.append`), `SmartWebUI.append(target, { parent, node | nodes })` for streaming growth, `SmartWebUI.adopt(target)` for server-rendered markup, `SmartWebUI.history(target)` → `{ undo(), redo(), clear(), entries, canUndo, canRedo }`, `SmartWebUI.validateSurface(surface)` → `{ valid, errors, issues: [{ path, message }] }`, `SmartWebUI.snapshot(target)` → `{ capturedAt, nodes: { [id]: { type, value?, checked?, selected?, expanded?, step?, open?, hidden? } } }`, `SmartWebUI.loadCatalog()`. Form validation is separate: `SmartWebUI.validate(form, rules, { summary })` on the core runtime (do not pass surface JSON to `validate()`).
- Application helpers: `copy(text)`, `confirm(options)`, formatters, `debounce`, `throttle`, `shortcuts.register()`, `observeBreakpoint()`, `observeLoadMore()`, `observeConnectivity()`, `focusFirst()`, `trapFocus()`, `trackDirty()`, `queryState.read/write/apply/bind`, `virtualize()`, and `scrollToTop()`.
- Server-side rendering: `smartwebui-surface.php` (PHP 8.0+, zero dependencies) emits the same semantic HTML with stable `data-smart-id` attributes and an embedded declaration. `SmartWebUISurface::container($surface)` returns a self-adopting block; `SmartWebUI.adopt("#id")` registers it in the browser without a rebuild, after which `patch()`, `snapshot()`, and `history()` work normally.
- Payment nodes are intent-only: the host mounts Stripe Elements via `SmartWebUIStripe.mount(slotId, { publishableKey, clientSecret })`. Keys, secrets, and card data never enter agent JSON. `elementType` accepts any Element — including `"address"` (with `addressMode: "billing" | "shipping"`) and `"expressCheckout"` for Apple Pay / Google Pay; `elementOptions` is forwarded to `elements.create()` verbatim.
- Events (bubbling CustomEvents): `smart:action`, `smart:change`, `smart:select`, `smart:combobox`, `smart:multiselect`, `smart:date`, `smart:time`, `smart:range`, `smart:rating`, `smart:tags`, `smart:tab`, `smart:accordion`, `smart:breadcrumbs`, `smart:step`, `smart:slide`, `smart:sort`, `smart:table-select`, `smart:table-action`, `smart:confirm`, `smart:toast-action`, `smart:chip-remove`, `smart:attachment-remove`, `smart:chart-select`, `smart:copy`, `smart:connectivity`, `smart:dirty`, `smart:query-state`, `smart:virtualize`, `smart:update`, `smart:patch`, `smart:surface`, `smart:adopt`, `smart:theme`, `smart:density`, `smart:material`, `smart:compat`, `smart:countdown`, `smart:countdown-expire`, `smart:locale`, `smart:validate`, `smart:quantity`, `smart:otp`, `smart:strength`, `smart:file`, `smart:upload-progress`, `smart:upload-done`, `smart:upload-error`, `smart:ready`, `smart:agent-ready`, `smart:stripe-ready`, `smart:payment-ready`, `smart:board`, `smart:move`, `smart:send`.

## Do not (agents)

- Do not pass surface JSON to `SmartWebUI.validate()` — use `SmartWebUI.validateSurface(surface)` for declarations; `validate(form, rules)` is for HTML forms only.
- Do not put publishable keys, client secrets, card data, or authoritative charge amounts in agent surfaces — host mounts payment UI and charges server-side.
- Do not put HTML strings inside surface JSON — use catalog node types; agents may write hand-authored <code>smart-*</code> HTML directly when that fits the host workflow.
- Do not assume legacy browsers — target releases from the preceding 36 months only.
- Prefer server render + `SmartWebUI.adopt()` when the host is PHP or can emit first paint from `smartwebui-surface.php`.
- Treat agent `text` as untrusted copy — it can mislead users even when structurally valid.

## Theming

- Everything is token-driven (`--smart-*` CSS custom properties): accent, surfaces, text, spacing (0–12), radius, shadows, motion, z-index ladder (`--smart-z-raised/sticky/tooltip/toast/banner`), overlay scrim.
- `SmartWebUI.setTheme("light" | "dark" | "auto")`, `setDensity("comfortable" | "compact")`, `setMaterial("solid" | "liquid")`.
- Buttons support `SmartWebUI.setBusy(button, true)` for in-flight states.
