Release history

Collaborative components. Version 1.2 adds three interactive families that real support, project, and messaging products need — a rich-text editor, a Kanban board, and conversation + composer chat primitives — all framework-free and token-driven.

• RichText editor. data-smart-richtext turns any container into a contenteditable rich-text field with a toolbar (bold, italic, lists, links), sanitized HTML output via a built-in tag allowlist (subset with data-smart-richtext-allow, e.g. p, br, strong, em, ul, ol, li), and a hidden input that stays in sync for form submission. Emits smart:change with { value, control }. The toolbar uses the same smartwebUI buttons and icons as the rest of the library.
• Kanban board. data-smart-board renders columns and cards with drag-and-drop reordering across columns. DnD is keyboard-accessible (focus a card, press Enter or Space to lift, arrow keys to preview a move, Enter or Space to drop, Escape to cancel), works with pointer and touch, and emits smart:board plus a compatibility smart:move event with the card ID, source and target columns, and indexes. No jQuery UI or external DnD library.
• Conversation + Composer. data-smart-conversation renders a scrollable message list with avatars, timestamps, and sender alignment; data-smart-composer renders a textarea with a send button, auto-resize, and Enter-to-send (Shift+Enter for newline). Together they cover ticket threads, live chat, and project comment flows.
• Icon alias map. SmartWebUI.icon() and the PHP se_icon() helper resolve common alternate icon names (e.g. house → home, check-circle → circle-check) so applications can use natural names without maintaining a custom map.
• Application layout utilities. Generic helpers for page shells, auth columns, reading-width content, card grids, and log panels — no product-specific class names. Includes smart-page-main, smart-shell-main, smart-cluster--center, smart-stack--tight, smart-auth-layout, smart-auth-logo, smart-reading-card, smart-tile-card, smart-grid--cards, smart-grid--tiles, smart-grid--pickers, smart-card--picker, smart-card__feature-icon, and smart-log-panel. Documented in the README layout table and on docs.php.
• Page header toolbar. The reusable smart-page-header--toolbar modifier and smart-page-header__toolbar element give headers a responsive, single-row home for filters, search, view controls, and a primary page action. Controls wrap naturally on smaller screens without application-specific CSS.
• Card and picker grids. Equal-height card grids (smart-grid--cards), tile grids with larger feature icons (smart-grid--tiles, smart-card__feature-icon), and centered picker tiles (smart-grid--pickers, smart-card--picker). Card title icons scale with the heading.
• Form sizing refresh. Comfortable-density defaults are roomier: control height 3rem, wider horizontal padding, larger label and input type, and vertical input padding derived from control height. New tokens --smart-form-gap and --smart-field-gap widen row spacing in form.smart-stack, card bodies, dialog bodies, and fieldsets; grids containing fields get a wider column gap. Dialog default width is 40rem with more internal padding; auth layout max width is 44rem. Filter toolbars still use smart-control-sm.
• Documentation. Token reference, utilities, and layout sections on docs.php now cover the new form spacing tokens and application layout helpers. The README layout utilities table lists every helper class.

No breaking changes. The surface protocol remains smartwebui.surface/1.0.

The application release. Version 1.1 grows smartwebUI from a component collection into a complete, dependency-free application foundation, with a native icon language and the patterns real products repeatedly need. This is the release for ambitious web apps.

• Carousels and lightbox. One Carousel family adds momentum media browsing: a snap-scrolling slide strip with iOS-style page dots, an optional autoplay that pauses on hover, focus, and offscreen, a gallery grid variant, and a fullscreen native-dialog viewer with swipe navigation, drag-to-dismiss, and pinch, double-tap, ⌘-scroll, or keyboard zoom (1–4×, reset on navigation). Slides accept captions and nested catalog content over the media; image URLs follow the surface src policy; smart:slide reports the active index and the snapshot records it.
• 500 stable symbols. The generated SVG sprite includes canonical names and compatibility aliases, while a searchable JSON catalog carries tags, categories, and directional metadata. The runtime pins sprite and catalog URLs to the loaded catalog payload (?v=version.count), so a rebuilt sprite can never lag a fresh catalog in a browser cache — the mismatch that renders blank icons.
• Any size. --smart-icon-size accepts every valid CSS length, from pixels and ems to viewport units and clamp(); stroke weight is independently adjustable.
• Motion utilities. Opt-in entrance, exit, and one-shot attention effects add a compact animation vocabulary for product interfaces. Timing, delay, easing, and iteration count are locally token-controlled; logical start/end directions mirror in RTL and every effect respects reduced-motion preferences.
• Application utilities. Public clipboard and confirm helpers, Intl formatters, debounce/throttle, breakpoint observation, infinite-scroll sentinels, dividers, keyboard hints, line clamps, sticky helpers, and tablet/desktop utilities stay small and framework-free.
• Layout utilities. Spacing steps run 0–8 with complete logical padding and margin axes (pt/pb/ps/pe, mt/mb/ms/me, mx/my). .smart-skip-link provides a focus-revealed bypass to the main landmark.
• One rendering contract. Authored HTML, SmartWebUI.icon(), agent Icon nodes, icon-bearing buttons, and the PHP renderer use the same sprite; action and status controls no longer depend on font glyphs.
• Accessible and international. Decorative icons are hidden, standalone icons accept labels, and directional symbols mirror automatically in RTL layouts.
• Complete chrome. AppHeader adds horizontal navigation and mobile collapse; AppShell gains nested disclosure groups; Footer completes the Header / Footer family, while consent is an Alert placement.
• Production tables. Sticky headers, expandable rows, column widths, totals, and a page-size selector cover dense admin and reporting workflows.
• Advanced forms and files. Field gains multi-select, dual numeric range, masks, rating, and color controls; the List family gains post-upload attachments.
• Safer form summaries. SmartWebUI.validate() builds the FormErrors summary with DOM text nodes instead of HTML interpolation.
• Command-first navigation. CommandPalette pairs live filtering and keyboard result navigation with a public, normalized shortcut registry.
• Persistent product data. Avatar gains groups and presence; List gains timeline, key-value, notification, and attachment variations; Progress gains a circular ring variation.
• Frosted Liquid art direction. A deeper blur substrate, asymmetric refraction, bright upper rims, and quiet lower-edge depth give controls and content surfaces a genuine frosted-glass character; connected split actions still share one glass container and accessibility preferences retain priority.
• Badge labels without a marker. .smart-badge--plain (agent plain) hides the leading status dot when the badge is a classification, not a live state.
• Hardening details. Toast placement, textarea counters, input icons, connectivity and scroll-to-top affordances, collapsing breadcrumbs, public focus and dirty/query-state helpers, fixed-row virtualization, accordion events, and z-index utilities close the remaining application-level gaps without adding component families.
• One additive contract. The browser renderer, dependency-free PHP renderer, TypeScript types, catalog, docs, and agent guidance all expose the same 34 components and 4 layout primitives.
• Catalog coherence. Split actions remain Button, advanced controls remain Field, structured feeds remain List, groups remain Avatar, and consent remains Alert. Existing Card, Badge, Tabs, Dialog, Menu, Tooltip, Stepper, and Table variations are catalog-exposed.
• Inventory, catalog, and contract clarity. HTML families (38) and catalog types (34 + 4, including Icon) are labeled as two lists. Field and List catalog events match the 1.1 runtime. The optional PHP renderer is documented as the included smartwebui-surface.php helper, not as the absence of PHP. Showcase variation cards no longer reuse family numbers 34–48.
• A clearer site experience. The landing page now presents a dashboard composition, the full style-switchable catalog lives in demo.php, and the agent surface lab has its own focused agents.php destination.

No breaking changes. The surface protocol remains smartwebui.surface/1.0.

Contract hardening and maintenance. This patch release aligns every shipped description of the surface protocol and fixes history edge cases without changing the protocol version.

• Server validation parity. The PHP renderer now rejects unknown node properties, enforces required properties, applies the node limit during traversal, and validates nodes nested inside tabs, accordions, and steppers.
• Reliable patch history. Undo restores the complete prior node after data.patch, handles node.upsert by its node ID, and records multi-operation inverses in execution order.
• Streaming ID safety. A node.append batch now rejects duplicate stable IDs before mounting the duplicate.
• Catalog alignment. node.append is included in the machine-readable patchOperations list.
• TypeScript clarity. Surface-validation and form-validation issues have distinct types, with a deprecated compatibility union for the previous shared name.
• Inventory clarity. Documentation consistently distinguishes the 33-family homepage showcase from the 34-family component reference, where Payment is demonstrated in the reference and agent demo.
• Shared demo stability. Page-specific customizer controls are now guarded when the shared showcase script runs on documentation, changelog, or agent-demo pages.

No breaking changes. The surface protocol remains smartwebui.surface/1.0.

Wider vocabulary, longer reach. This release grows the component vocabulary — files, print, and input ergonomics — and extends the surface contract from first paint on the server to live token streams.

• Dropzone file upload with progress. File gains drag-and-drop, per-file progress events, and client-side validation through data-max-size and accept.
• Print and document styles. A base @media print layer, a .smart-no-print utility, and a print-optimized document card for printable pages such as invoices, quotes, and receipts.
• Vertical tabs. A vertical variant of the tabs family for settings-style layouts.
• Quantity stepper. .smart-quantity with [data-smart-step] buttons that respect min, max, and step; part of Fields as Field control: "quantity".
• Split-button dropdown. A primary action with an attached menu of secondary actions.
• Password strength meter. A Field extension that scores password input and reports missing requirements.
• Server-side surface rendering. A reference renderer in PHP (and the spec for any language) that emits the same semantic HTML as the browser runtime. Agents compose, the server renders first paint, and the browser runtime adopts the DOM by stable ID for patching — turning "agent UI" into "progressively enhanced agent UI."
• Streaming surfaces. An append-friendly render mode for SSE/WebSocket token streams — partial Trees/Lists that grow as the model emits. Every serious LLM product needs this and nobody has a safe, validated answer.
• Patch history / undo. SmartWebUI.history() records surface operations with undo/redo, so agents can roll back their own UI mistakes.
• Form validation helper. SmartWebUI.validate(form, rules) wires aria-invalid, hints, and the FormErrors summary together.
• API clarity. SmartWebUI.validate(form, rules) is the form validation helper; surface declarations are checked with SmartWebUI.validateSurface(surface). The 1.0.1 validate() alias on the agent runtime was removed to keep one meaning per name.
• OTP verification input. .smart-otp digit rows with auto-advance, arrow-key movement, paste distribution, a synced hidden input, and smart:otp events — Field control: "otp" with length in the catalog and both renderers.
• Countdown helper. SmartWebUI.countdown(el, seconds, { warnBelow, onExpire }) or data-smart-countdown markup for the session-timeout pattern, with a stop/start/reset controller and smart:countdown events.
• Scroll panes. .smart-scroll-y/x with contained overscroll plus .smart-pane-fill/tall/screen heights (--smart-pane-offset) for messenger-style layouts.
• Stripe Address + Express Checkout. The companion's mount() now documents and supports elementType: "address" (with addressMode: "billing" | "shipping") and "expressCheckout" for Apple Pay / Google Pay, with elementOptions forwarded verbatim.
• i18n chrome strings. A SmartWebUI.setLocale({ … }) dictionary for component chrome ("Select dates", "Close", placeholders), complementing the existing Intl-based dates and currency and letting agents localize surfaces without re-rendering.
• Source license. smartwebUI ships under the smartwebUI Source License — free to use and customize for your own projects; redistributing modified or rebranded versions requires written permission. See LICENSE.md in the distribution archive.

One agent-runtime breaking change: rename validate(surface) → SmartWebUI.validateSurface(surface) (the 1.0.1 alias is removed; form validation now owns validate()). The surface protocol stays at smartwebui.surface/1.0 (additive properties only); new components ship as HTML-first families.

Utility layer. The infrastructure between components — spacing, typography, visibility, and surface helpers — is now part of the library instead of host-app homework.

• Spacing utilities. .smart-p-*, .smart-px-*, .smart-py-*, .smart-m-* (steps 0–5), .smart-m-auto / .smart-mx-auto, and .smart-gap-* for stack, cluster, and grid.
• Layout utilities. .smart-container--sm/md/lg width caps (backed by new --smart-container-* tokens), fixed .smart-grid--2/3/4 grids with .smart-span-2 / .smart-span-full.
• Typography utilities. Sizes .smart-text-xs–xl, semantic tones, logical alignment, .smart-truncate, .smart-balance, .smart-mono, and .smart-font-* weights.
• Visibility utilities. .smart-hidden, .smart-invisible, .smart-hidden-mobile / .smart-visible-mobile (50rem breakpoint), plus SmartWebUI.hide(el) / SmartWebUI.show(el) and a universal hidden property on agent nodes.
• Surface utilities. .smart-elevated-0/1/2, .smart-rounded-sm/md/lg/full, .smart-bordered, .smart-w-full, .smart-min-w-0, .smart-overflow-x-auto.
• Media ratio utilities. .smart-ratio-1x1 / -4x3 / -16x9 / -21x9, plus two markup behaviors: data-smart-collapse="#id" for remote disclosure toggles and data-smart-scrollspy for table-of-contents highlighting.
• Native validation states. :user-invalid / :user-valid styling, automatic required markers, and .smart-error--live messages that reveal only while invalid — complementing server-side .smart-field--invalid.
• RTL pass. Logical properties verified across the library, with physical-direction corrections for the switch knob, combobox chevron, calendar nav glyphs, and toast region.
• Opt-in compatibility banner. data-smart-compat on <html> feature-detects the 36-month baseline and shows a dismissible update-browser warning on unsupported clients, with a smart:compat event for telemetry.
• Layering tokens. --smart-z-raised/sticky/tooltip/toast/banner replace hardcoded z-indexes so host apps can restack the library. Stepper panel swaps now run through the View Transitions API (like SmartWebUI.update()) with a fade-slide fallback, and .smart-reveal adds scroll-triggered entrance animation with --smart-reveal-delay stagger.
• Agent loop closure. SmartWebUI.snapshot(target) reads values, selections, and progress back from a live surface by stable id, validateSurface() gains structured issues with JSON paths (also exposed as a validate() alias in 1.0.1 only — removed in 1.0.2), and a new /llms.txt teaches coding agents the library's conventions, catalog, and events.
• Media polish. Native <figure>/<figcaption> base styling (caption tone and spacing, no classes) and .smart-object-contain / -cover / -fill / -scale-down utilities as an escape hatch from cover-cropped ratio boxes.
• Sizing utilities. Dimension classes (.smart-w-25/33/50/66/75/full, .smart-w-auto, .smart-h-full) and generic control sizing — .smart-control-sm / .smart-control-lg override --smart-control-height locally, so inputs, selects, date pickers, segmented controls, tabs and buttons align at any size.
• The agent demo is now interactive end-to-end. A live surface JSON editor with validateSurface() feedback (issues listed with their JSON paths), three presets (dashboard, checkout with a Payment slot, settings form), and a real-time snapshot() state panel that follows every interaction and patch.
• E-commerce. Optional smartwebui-stripe.js companion lazy-loads Stripe.js and maps --smart-* tokens to the Elements appearance API (theme/density/material aware). New agent Payment node renders an intent-only checkout slot the host mounts into — keys, secrets, and card data never enter agent JSON.
• Fix. Date pickers now close their popover and return focus to the trigger once a day (or a completed range) is chosen — the grid re-render was detaching the clicked day before the popover lookup ran.

No breaking changes. All utilities live in @layer smart.utilities and reference design tokens, so density and overrides apply automatically.

Initial release. A standards-native UI library for building polished web interfaces without a framework, compiler, Node.js runtime, or dependency — designed for server-rendered applications while remaining stack-independent.

• Thirty-three showcase families. Semantic HTML mapped to 27 agent catalog types plus four layout primitives. Field covers combobox, search, file, date, time, tags, and date range; Dialog variant: "confirm" covers confirm dialogs. App shell collapse, table bulk actions, busy buttons, input add-ons, and Stepper are first-class.
• Themes, density, and materials. Light and dark themes resolved through color-scheme and light-dark(), compact density, and the optional Liquid material with pointer tracking that respects reduced motion, reduced transparency, increased contrast, and forced colors.
• Optional behavior script exposing SmartWebUI. Live region toasts, View Transition updates, theme, density, and material preferences, and hydration for dynamically inserted components. update() inserts plain text by default; HTML requires an explicit { html: true } opt-in.
• Agent runtime. Declarative, validated surfaces with stable IDs and live data.patch, node.upsert, and node.remove operations, plus a machine-readable component catalog for generative systems.
• Accessibility and quality. Component-level WCAG 2.2 AA engineering target with documented release gates, a component showcase, agent demo, and this documentation set.

Read the documentation, try the agent demo, or browse the component showcase.