awaforge

Index by use case

Apache-2.0Release 1L3

You know what you want to do — here is where to go. This index complements the per-module table of contents (api/) and the chronological guides (rendering pipeline, security).

Bootstrap

You want to… Read…
Start an empty fw app getting-started.md
Build a complete app in 70 LOC tutorial-todo.md
Understand basic security security.md
Understand the factory pattern module-pattern.md
Create your own module module-creation-workflow.md

Rendering and templates

You want to… API to use
Display structured HTML parser + template + uiSession
Keyed list with incremental diff ui.list
Adopt an SSR row without rebuild list.adopt
Hydrate an SSR page ui.hydrate
Hydration with recovery on mismatch ui.hydrate(items, { onMismatch: 'rebuild' })
Reusable component component
CSS scoped to a component component.define({ css: '& { ... }' })
Validate a component's props component.define({ props: { x: { type, required, validator } } })
Custom HTML tags template.registerTags
Hot-reload tags (dev) template.reloadTags, template.unregisterTag
Theme tokens (light/dark) themeTokens
Material/Tailwind preset themeTokens.factory().presets.material

Reactivity

You want to… API
Observable value signal.create(v)
Explicit derived value signal.derived([a, b], (a, b) => …)
Auto-tracked side effect signal.effect(() => …)
Async resource (loading/value/error) signal.resource(fetcher)
Async resource derived from signals signal.derivedAsync([deps], fetcher)
Multiple set in one notify signal.batch(() => { a.set(...); b.set(...); })
Read without subscribing signal.untrack(() => sig.get())
Bind a signal to the DOM ui.bind(sig, blockId, 'text' | 'class:NAME' | 'style:PROP' | 'prop:NAME' | 'attr-name')

Lists and collections

You want to… API
Keyed list with delta sync list.sync(items) returns {added, kept, updated, removed, reordered}
Preset shallow / deep eqFn ui.list(..., { eqFn: 'shallow' })
Item enter/leave transitions ui.list(..., { onEnter, onLeave }) (Promise-aware)
Virtualised list 10⁴+ items virtualScroll + ui.mount

Routes / navigation

You want to… API
Hash-based router route
Guard before entry route.on('x', '/p', fn, { beforeEnter: () => check() })
Nested routes (layouts) route.on('child', '/sub', fn, { parent: 'parent-name' })
Cancel navigation beforeLeave: () => false

Forms

You want to… API
Two-way bind input ↔ state form.create + attach
Sync validators fields: { x: { validate: v => v ? null : 'Required' } }
Async validators validate: async v => await checkRemote(v)
Repeatable fields fields: { emails: { type: 'array', itemValidate } } + form.array('emails')
dirty/touched/submitting state form.snapshot()

Events and interactions

You want to… API
Named managed listener events.on(name, el, type, fn)
Delegation by selector events.delegate(root, type, selector, fn)
Bulk cleanup events.scope('namespace') then .clear()
Auto-cleanup when element leaves DOM events.enableAutoCleanup()
Gestures (pan/pinch/tap/longpress) gesture.attach(el)
Native drag & drop dnd.draggable / dnd.dropTarget
Keyboard shortcuts keybindings.create
Cleanup a shortcut group keybindings.scope()

Accessibility

You want to… API
Announce a message to screen readers a11y.announce(text, 'polite' | 'assertive')
Set ARIA attributes in batch a11y.aria(el, { label, pressed, expanded })
aria-labelledby / aria-describedby a11y.labelledBy(el, idsOrEls)
Trap focus in a modal focus.trap(el, opts)
Restore focus on close focus.pushFocus() / focus.popFocus()
Reduced motion? a11y.prefersReducedMotion()

Lifecycle and integrations

You want to… API
Code after a block mounts ui.onMount(blockId, fn)
Code before unmount ui.onUnmount(blockId, fn)
Adopt an external resource (auto-dispose) ui.adopt(blockId, abortController)
Plug in a standalone widget ui.mount(blockId, slotName, factory)
Application event bus eventBus.create() + bus.scope() via ui.mount
Modal / portal ui.portal(name, { to: document.body })

SSR & hydration

You want to… API
Render server-side (Node/Bun) @awacloud/back-shared/ssr
Produce hydratable HTML render.toHTML(parsed, data, { hydrate: true, idPrefix })
Adopt the DOM client-side ui.hydrate(items, { idPrefix })
Adopt iterate rows list.adopt(initialRows, { idPrefix })
Recovery when SSR diverges ui.hydrate(..., { onMismatch: 'rebuild' })

Security

You want to… API
Verify a user URL secPolicy.isSafeUrl(url)
Verify an id/name value (clobber) secPolicy.isClobberValue(attr, value)
Verify a CSS value secPolicy.isSafeCss(prop, val)
Sanitise user-supplied HTML sanitize.sanitizeHtml(html)
CSP nonce for injected <style> template.setNonce(value) or csp-nonce meta

Debug & instrumentation

You want to… API
Snapshot a session's state devtools.inspect(ui)
Human-readable ParseResult display devtools.dumpTemplate(parsed)
Profile a function devtools.profile(fn) → { result, durationMs }
Profile async devtools.profileAsync(async fn)
Profile segments const t = devtools.timer(); t.mark('a'); t.mark('b'); t.end()
Structured logger errors.factory().logger({ level, prefix, sink })
Boundary around a render errors.factory().boundary(ui, 'panel', { fallback })

Useful web standards

You want to… API
UUID v4 / v7 uuid.v4()
Secure random random.bytes(n)
Monotonic timing clock.monotonic() (performance.now is blocked)
WebAuthn (passkeys) webauthn
WebRTC peer-to-peer webrtc
Service worker / cache serviceWorker

See also