Documentation
¶
Overview ¶
CSSARIAJS is the tiny ARIA state synchroniser for CSS-signal scopes that need synthesized state the user agent does not maintain on a native control (tabs, listbox, disclosure/dialog/popover). It is injected ONLY when such a role is used, so every other CSS-signal page stays fully zero-JS. It derives aria-selected / aria-expanded from the checked state of the native radio/checkbox each trigger labels - the same state the `:has()` stylesheet already tracks - so there is no per-interaction bookkeeping.
LegacyHasJS is the scoped shim that drives the class-based stylesheet emitted in legacy/hybrid compat modes. Browsers without :has() cannot express "scope root whose controller input is checked" in CSS, so this script mirrors each hidden controller input's checked state onto its scope root as a `<token>-on` class (and the focused input's trigger label as `krc-f`). The legacy stylesheet keys off those classes instead of :has().
It is a no-op where :has() is supported (hybrid mode guards the injection with a feature query) and idempotent via window.__krateHasShim, so duplicate injection is harmless. Keep it small: it ships on legacy CSS-signal pages.
Index ¶
- Constants
- Variables
- func EmitMeta(tree *irtree.ComponentTree, result *EmitResult)
- func GenerateNewHydrationJS(result *EmitResult) string
- type ComponentTier
- type EmitResult
- type Emitter
- type SSREval
- func (e *SSREval) BindLocalVars(body []ast.Stmt)
- func (e *SSREval) Errors() []error
- func (e *SSREval) Eval(expr ast.Expr) string
- func (e *SSREval) SetBindings(bindings map[string]string)
- func (e *SSREval) SetCVAFactories(factories map[string]*irtree.CVASpec)
- func (e *SSREval) SetCodeTheme(theme string)
- func (e *SSREval) SetContextDefaults(defaults map[string]string)
- func (e *SSREval) SetEvalJS(fn func(code string) (string, error))
- func (e *SSREval) SetGoComponents(comps map[string]irtree.GoComponentRef, ...)
- func (e *SSREval) SetRestProps(rest map[string]map[string]ast.Expr)
- type SlotOutput
- type TierClassifier
- func (tc *TierClassifier) All() map[string]*TierInfo
- func (tc *TierClassifier) Classify(name string, tier ComponentTier, sourceFile string)
- func (tc *TierClassifier) Get(name string) *TierInfo
- func (tc *TierClassifier) GetTier(name string) ComponentTier
- func (tc *TierClassifier) HasRuntimeComponents() bool
- func (tc *TierClassifier) HasServerComponents() bool
- func (tc *TierClassifier) IsRuntime(name string) bool
- func (tc *TierClassifier) IsServer(name string) bool
- func (tc *TierClassifier) IsStatic(name string) bool
- func (tc *TierClassifier) RuntimeComponentNames() []string
- func (tc *TierClassifier) ServerComponentNames() []string
- func (tc *TierClassifier) StaticComponentNames() []string
- type TierInfo
Constants ¶
const CSSARIAJS = `` /* 506-byte string literal not displayed */
CSSARIAJS is the minified synchroniser (one delegated change listener plus an initial pass). Keep it small: it ships inline on ARIA-role pages only.
const HydrationBootstrapJS = `` /* 2785-byte string literal not displayed */
HydrationBootstrapJS is the shared hydration infrastructure appended to the runtime chunk instead of being emitted into every page's JS. It defines the slot lookup helpers, the XSS sanitizer, and the compact binding helpers (kbind*) that per-page hydration scripts call. It runs once per page load. On SPA navigation the router swaps in the new page's DOM and re-runs that page's hydration script, which calls refreshSlots() to rebuild the comment-marker cache against the new DOM.
const LegacyHasJS = `` /* 1541-byte string literal not displayed */
LegacyHasJS is the minified shim: one initial pass, delegated change/input/focus listeners, and a MutationObserver so state is also synced for markup inserted after load (SPA/router swaps). State changes resync only the affected scope root (not the whole document).
Variables ¶
var TierCommentPrefixes = map[string]ComponentTier{ "@client": TierClient, "@static": TierStatic, "@server": TierServer, "@runtime": TierRuntime, }
TierCommentPrefixes maps tier annotation comments to their tier.
Functions ¶
func EmitMeta ¶
func EmitMeta(tree *irtree.ComponentTree, result *EmitResult)
EmitMeta walks the tree and extracts Head/Script/Style content, routing MetaSlot children to the appropriate EmitResult fields.
func GenerateNewHydrationJS ¶
func GenerateNewHydrationJS(result *EmitResult) string
GenerateNewHydrationJS produces per-component scoped hydration code. The shared infrastructure (findSlot, __safe, $esc, kbind* helpers) lives in the runtime chunk (HydrationBootstrapJS); this only emits the page-specific signal declarations and compact binding calls, so pages with no client signatures produce no JavaScript at all.
Types ¶
type ComponentTier ¶
type ComponentTier int
ComponentTier classifies components into rendering strategies.
const ( TierClient ComponentTier = iota // Default: full SSR + client hydration TierStatic // Compile-time only, no client JS TierServer // Build-time evaluation, HTML output only TierRuntime // Serve-time evaluation via QuickJS, streamed to client )
func ClassifyComponent ¶
func ClassifyComponent(fn *ast.FnDecl) ComponentTier
ClassifyComponent determines a component's tier from its leading comments. The AST doesn't store comments directly, so this scans the first statement of the body for a string literal containing a tier annotation (e.g. "@static"). For production use, the build system should call TierClassifier.Classify() based on config or file-level annotations.
func (ComponentTier) IsClient ¶
func (t ComponentTier) IsClient() bool
IsClient returns true if the component needs client hydration.
func (ComponentTier) IsRuntime ¶
func (t ComponentTier) IsRuntime() bool
IsRuntime returns true if the component is evaluated at serve time via QuickJS.
func (ComponentTier) IsServer ¶
func (t ComponentTier) IsServer() bool
IsServer returns true if the component is evaluated at build time.
func (ComponentTier) IsStatic ¶
func (t ComponentTier) IsStatic() bool
IsStatic returns true if the component is compile-time only.
func (ComponentTier) String ¶
func (t ComponentTier) String() string
String returns the tier name for debugging.
type EmitResult ¶
type EmitResult struct {
HTML string
HeadHTML string
ScriptHTML string
StyleHTML string
Signatures []irtree.ComponentSignature
HasLinks bool
UsedFuncs map[string]bool
UsedCSS map[string]bool
// ListComponents are the client component functions referenced by dynamic
// list slots (e.g. <Toast> in a .map() body). They're emitted into the
// hydration scope so the runtime can re-render lists via h(Component, ...).
ListComponents []*ast.FnDecl
// Errors holds diagnostics for unsupported constructs encountered during
// render. A non-empty set means the build must fail rather than ship
// silently empty/wrong output.
Errors []error
// GoRenders are build-time Go-component render requests; the build renders
// them via the Go host and substitutes HTML at the markers.
GoRenders []irtree.GoRenderRequest
}
EmitResult consolidates all page output from the emitter.
type Emitter ¶
type Emitter struct {
// IconResolver compiles an <Icon name="..."> to its SVG markup at SSR
// time. It's wired by the build pipeline to resolve icons whose `name`
// attribute is a runtime-evaluated expression (e.g. name={icon}). When
// nil, dynamic-name icons are left as unknown components.
IconResolver func(name string, attrs []*ast.JSXAttr) (string, bool)
// EvalJS is wired by the build to the embedded QuickJS engine. It evaluates
// self-contained JS expressions with full built-ins (Date, Math, String,
// Number, ...) so server-component SSR computes globals like Date.now()
// with real JS semantics instead of Go approximations.
EvalJS func(code string) (string, error)
// GoComponents maps imported Go component names to their refs. Wired by the
// build pipeline; SSREval renders them via the shared goCollector.
GoComponents map[string]irtree.GoComponentRef
// CodeTheme is the chroma theme used to highlight <Code>/<SyntaxHighlight>
// during SSREval. It must match the stylesheet generated for the same theme
// (syntaxhighlight.CSSForTheme). Wire it from the build; empty selects the
// default theme.
CodeTheme string
// contains filtered or unexported fields
}
Emitter walks a ComponentTree and produces HTML + hydration metadata.
func (*Emitter) Emit ¶
func (e *Emitter) Emit(tree *irtree.ComponentTree) *EmitResult
Emit walks the ComponentTree and produces an EmitResult.
type SSREval ¶
type SSREval struct {
// Meta content captured from <Head>/<Script>/<Style> elements encountered
// during evaluation. Signal-less components that go through the SSREval
// path (e.g. a docs layout wrapper) still inject their <Head> stylesheet
// links and <Script> tags via these fields; the emitter routes them into
// the page's HeadHTML/ScriptHTML/StyleHTML.
HeadHTML string
ScriptHTML string
StyleHTML string
// contains filtered or unexported fields
}
SSREval is a lightweight SSR evaluator that produces HTML output only. It has NO signal tracking, NO handler collection, NO path tracking. It replaces the old evalExpr/renderExpr triple-return monster.
func NewSSREval ¶
NewSSREval creates a new SSR evaluator.
func (*SSREval) BindLocalVars ¶
BindLocalVars evaluates top-level const/let/var declarations in a function body and binds them so return-statement evaluation resolves locals like `var className = "..." + side`. Must run before Eval on the return value. Also evaluates for-loops that build arrays via `.push(<JSX/>)` so components like OTPField render their statically-built element lists.
func (*SSREval) SetBindings ¶
SetBindings sets the variable bindings for evaluation.
func (*SSREval) SetCVAFactories ¶ added in v0.4.0
SetCVAFactories installs the module-wide cva factory table.
func (*SSREval) SetCodeTheme ¶ added in v0.4.0
SetCodeTheme installs the chroma theme for compile-time code highlighting.
func (*SSREval) SetContextDefaults ¶ added in v0.4.0
SetContextDefaults installs the module-wide context-default table.
func (*SSREval) SetEvalJS ¶
SetEvalJS installs the expression-evaluation hook backed by the embedded QuickJS runtime. See the evalJS field docs.
func (*SSREval) SetGoComponents ¶ added in v0.4.0
func (e *SSREval) SetGoComponents(comps map[string]irtree.GoComponentRef, enqueue func(callID, name, propsJSON string) string)
SetGoComponents installs the Go-component table + enqueue hook.
type SlotOutput ¶
type SlotOutput struct {
HTML string
Signatures []irtree.ComponentSignature
HeadHTML string
ScriptHTML string
StyleHTML string
Orphans []orphanBinding
GoRenders []irtree.GoRenderRequest
}
SlotOutput is the result of emitting a single slot node. Beyond HTML and signatures it carries subtree-local metadata (Head/Script/Style content) and orphan bindings, merged into the parent output in document order.
type TierClassifier ¶
type TierClassifier struct {
// contains filtered or unexported fields
}
TierClassifier tracks component tier classifications across the build.
func NewTierClassifier ¶
func NewTierClassifier() *TierClassifier
NewTierClassifier creates a new classifier.
func (*TierClassifier) All ¶
func (tc *TierClassifier) All() map[string]*TierInfo
All returns all classified components.
func (*TierClassifier) Classify ¶
func (tc *TierClassifier) Classify(name string, tier ComponentTier, sourceFile string)
Classify records a component's tier.
func (*TierClassifier) Get ¶
func (tc *TierClassifier) Get(name string) *TierInfo
Get returns a component's tier info, or nil if not classified.
func (*TierClassifier) GetTier ¶
func (tc *TierClassifier) GetTier(name string) ComponentTier
GetTier returns a component's tier, defaulting to TierClient.
func (*TierClassifier) HasRuntimeComponents ¶
func (tc *TierClassifier) HasRuntimeComponents() bool
HasRuntimeComponents returns true if any component uses the runtime tier.
func (*TierClassifier) HasServerComponents ¶
func (tc *TierClassifier) HasServerComponents() bool
HasServerComponents returns true if any component uses the server tier.
func (*TierClassifier) IsRuntime ¶
func (tc *TierClassifier) IsRuntime(name string) bool
IsRuntime checks if a named component is serve-time runtime.
func (*TierClassifier) IsServer ¶
func (tc *TierClassifier) IsServer(name string) bool
IsServer checks if a named component is build-time server.
func (*TierClassifier) IsStatic ¶
func (tc *TierClassifier) IsStatic(name string) bool
IsStatic checks if a named component is static.
func (*TierClassifier) RuntimeComponentNames ¶
func (tc *TierClassifier) RuntimeComponentNames() []string
RuntimeComponentNames returns all runtime component names.
func (*TierClassifier) ServerComponentNames ¶
func (tc *TierClassifier) ServerComponentNames() []string
ServerComponentNames returns all build-time server component names.
func (*TierClassifier) StaticComponentNames ¶
func (tc *TierClassifier) StaticComponentNames() []string
StaticComponentNames returns all static component names.
type TierInfo ¶
type TierInfo struct {
Tier ComponentTier
SourceFile string // file where the component is defined
ComponentName string
}
TierInfo holds classification metadata for a component during rendering.