API Reference
Public v0.1 API surface by package.
This page records the v0.1 public API shape. Rust crates remain internal and are not published to crates.io for v0.1.
@naos-ui/core
| Export | Stability | Notes |
|---|---|---|
state() | Public | Writable local state primitive. |
computed() | Public | Derived read-only value. |
effect() | Public | Lifecycle-aware effect and cleanup. |
event() | Public | Typed CustomEvent dispatch helper. |
on() | Public | Typed DOM listener helper with listener options and invocation-scoped abort signals. |
host() | Public | Current custom element, props, lifecycle signals, and update/task handle. |
formControl() | Experimental | Compiler-recognized form association helper for generated Custom Elements. |
Show | Public | Static conditional rendering primitive. |
ComponentOptions | Public | Flat styles metadata for component CSS. |
@naos-ui/runtime
Tiny platform helper runtime for generated output: events, scheduling, and hydration helpers. It is not a reconciler, virtual DOM, component runtime, or framework adapter.
@naos-ui/router
Optional browser-side router for Custom Element app shells.
| Export | Stability | Notes |
|---|---|---|
defineRoutes() | Experimental | Preserves route-table inference for path params. |
createRouter() | Experimental | Creates a router that mounts custom-element route targets into an outlet. |
redirect() | Experimental | Creates an action redirect result for route actions. |
NaosRouter | Experimental | EventTarget-backed router instance with start, stop, navigate, replace, submit, href, prefetch, back, forward, and reload. |
Mounted route elements receive an naosRoute property with the current route,
URL, params, search params, loader data, action data, navigation type, and abort
signal. Route records may define loader and action; native forms opt into
action handling with data-naos-action. The router intercepts only same-origin
anchors and explicit action forms it can handle and falls back to ordinary
browser behavior for external links, downloads, targets, and modified clicks.
@naos-ui/primitives
Experimental primitive Custom Elements authored in Naos .wc.tsx and compiled
for package distribution.
All primitives remain experimental. The package exposes Naos elements only; Zag machines and adapter helpers stay private under the package internals.
Actions And Structure
| Element | Key attributes | Events | Notes |
|---|---|---|---|
<naos-button> | variant, disabled, label | naos-press | Native button action primitive with slots, parts, and CSS custom properties. |
<naos-button-group> | orientation, label | None | Structural grouping for related actions. |
<naos-field> | label, hint, status, invalid | None | Label, hint, status, and layout shell. |
Forms And Inputs
| Element | Key attributes | Events | Form behavior |
|---|---|---|---|
<naos-checkbox> | name, value, checked, indeterminate, disabled, label | naos-change | Form-associated; supports submit, reset, FormData, and disabled fieldset propagation. |
<naos-toggle> | name, value, pressed, disabled, label | naos-change | Form-associated pressed/on-off control. |
<naos-switch> | name, value, checked, disabled, label | naos-change | Zag-backed switch with native form integration. |
<naos-number-input> | name, value, min, max, step, disabled, label | naos-change | Zag-backed spinbutton behavior with form integration. |
<naos-slider> | name, value, min, max, step, disabled, label | naos-change | Zag-backed single-value slider with pointer and keyboard behavior. |
<naos-pin-input> | name, value, count, otp, disabled, label | naos-change, naos-complete, naos-invalid | Multi-field code input with paste and keyboard behavior. |
<naos-tags-input> | name, value, delimiter, max, allow-duplicates, disabled, label | naos-change, naos-input, naos-highlight-change, naos-invalid | Token input with delimiter entry, paste handling, and delete controls. |
<naos-file-upload> | name, accept, multiple, max-files, disabled, label | naos-change, naos-invalid | File input with dropzone, picker trigger, list, delete, clear, and FormData support. |
<naos-rating-group> | name, value, count, disabled, label | naos-change, naos-hover-change | Rating control with pointer and keyboard selection. |
<naos-date-picker> | name, value, locale, placeholder, disabled, read-only, required, label | naos-change, naos-focus-change, naos-open-change | Single-date picker; public value and FormData value use ISO YYYY-MM-DD. |
<naos-editable> | name, value, placeholder, max-length, submit-mode, disabled, read-only, required, label | naos-change, naos-edit-change, naos-submit, naos-cancel | Inline editable text with preview/edit modes and form integration. |
Collections
| Element | Subcomponents | Events | Notes |
|---|---|---|---|
<naos-tabs> | <naos-tab>, <naos-tab-panel> | naos-change | Zag-backed tab collection with roving focus and selected panel mapping. |
<naos-radio-group> | <naos-radio> | naos-change | Form-associated radio collection with roving focus. |
<naos-segmented-control> | <naos-segmented-item> | naos-change | Single-selection segmented control. |
<naos-toggle-group> | <naos-toggle-item> | naos-change | Single or multiple toggle collection. |
<naos-select> | <naos-select-item> | naos-change, naos-open-change | Single-selection popup with typeahead and form integration. |
<naos-combobox> | <naos-combobox-item> | naos-change, naos-input, naos-open-change | Autocomplete combobox with popup items and form integration. |
<naos-listbox> | <naos-listbox-item> | naos-change, naos-highlight-change | Selection listbox with typeahead, disabled items, and form integration. |
Overlays And Disclosure
| Element | Subcomponents | Events | Notes |
|---|---|---|---|
<naos-menu> | <naos-menu-item> | naos-select, naos-open-change | Flat action menu with dismiss behavior and focus return. |
<naos-context-menu> | <naos-menu-item> | naos-select, naos-open-change | Context-triggered menu region. |
<naos-dialog> | None | naos-open-change | Modal dialog with backdrop, focus trap, scroll lock, dismiss, and focus return. |
<naos-popover> | None | naos-open-change | Positioned popover with Escape/outside dismiss and close trigger. |
<naos-tooltip> | None | naos-open-change | Hover/focus tooltip with Escape close. |
<naos-hover-card> | None | naos-open-change | Hover/focus preview card with positioned content. |
<naos-accordion> | <naos-accordion-item> | naos-change | Accordion collection with roving trigger focus and disabled item handling. |
<naos-collapsible> | None | naos-open-change | Disclosure primitive with trigger/content ARIA. |
Feedback
| Element | Key attributes | Events | Notes |
|---|---|---|---|
<naos-progress> | value, min, max, indeterminate, orientation, label, locale | naos-change | ARIA progressbar with part="track range value" and CSS custom properties. |
<naos-avatar> | src, alt, fallback | naos-status-change | Image loading state with fallback content. |
<naos-toast> | title, description, type, duration, closable, label | naos-create | Declarative trigger that creates a toast in the package toast store. |
<naos-toast-root> | label, placement | naos-status-change | Minimal notification region that renders store toasts and owns their lifecycle cleanup. |
Each component exposes stable part names, data-* state attributes, and
--naos-* CSS custom properties for styling. Declarative Shadow DOM output is
covered by the package demo build, but the components are not marked stable
until broader validation and documentation coverage are complete.
@naos-ui/compiler
type TransformResult = {
code: string
hasChanged: boolean
map?: unknown
}transformComponent() returns transformed code, optional source map data, and a
change flag. Compiler failures throw structured errors with diagnostics[].
@naos-ui/vite
naos(options) installs the Vite transform and emits prerender metadata by
default for DSD workflows. Set prerender: false to disable metadata emission.
Vite owns module graph, chunks, CSS imports, assets, and invalidation.
@naos-ui/cli
The naos binary exposes:
| Command | Purpose |
|---|---|
naos compile | Transform a .wc.tsx component. |
naos prerender | Emit explicit Declarative Shadow DOM host HTML. |
naos info | Print compiler, package, native target, and platform details. |