s&box/field-guide
 field-guide / building-ui
05/10
26.07
"@ref on a bare private field silently never assigns"

@ref on a private field compiles with only a CS0649 warning — the ref stays null at runtime. Bind to a property instead.

26.07
"Building a draggable slider with click-to-jump and drag-to-scrub"

No native drag helper exists for PanelComponent sliders — use the engine's SliderControl pattern: MousePanelEvent.LocalPosition over track width, with pointer-events routing.

26.07
"Building an s&box HUD"

One ScreenPanel host, static UIState for modals, self-closing panels, toast stack — BuildHash every flag the markup reads.

26.07
"Flex-grow track with a percentage-width child causes a layout feedback loop"

A flex-grow slider track holding a normal-flow fill child sized by width:N% balloons wider as the value increases — take the fill out of flow with position:absolute.

26.07
"My s&box UI won't update / is frozen"

BuildHash() is the only re-render trigger — hash everything the markup reads, including collection contents and flags.

26.07
"PanelComponent uses OnTreeBuilt, not OnAfterTreeRender"

OnAfterTreeRender(bool) is a Panel hook — on a PanelComponent it fails with CS0115; use parameterless OnTreeBuilt() or OnTreeFirstBuilt().

26.07
"Roboto Mono is the engine's monospace font"

s&box ships Roboto Mono (all weights) — JetBrains Mono and Consolas only resolve on dev machines with those system fonts.

26.07
"Runtime textures for UI panels must be assigned from C#"

SCSS background-image only resolves asset paths — runtime Texture objects must be assigned via Panel.Style.BackgroundImage in OnTreeBuilt.

26.07
"TextEntry is the house control, not HTML input"

Use TextEntry with onsubmit and OnTextEdited — standard Blazor input bindings compile but are not how the engine UI works.

26.07
"The Razor @namespace trap"

Razor classes get a RootNamespace/folder-derived namespace — declare @namespace and global using or C# can't find your panels.

26.07
"Too many font-size declarations corrupt UI text rendering"

Many selectors declaring font-size in one SCSS file can make text render as solid filled rectangles — carry hierarchy via font-weight/color instead.