canvas

canvas(...) is a low-level custom-drawing helper for Fission library authors.

It creates a fixed-size custom widget whose painter closure emits intermediate representation (IR) ids during lowering. That makes it useful for focused visual surfaces such as custom indicators, chart internals, or small decorative primitives when ordinary widget composition cannot express the shape clearly enough.

Most application authors should start with normal widgets such as Container, Composite, Row, Column, and Text. Those widgets are easier to theme, test, document, and make accessible. Reach for canvas(...) only when you need custom IR emission.

Example shape

use fission::prelude::*;

let surface: Widget = canvas(Some(120.0), Some(24.0), |_cx| {
    // Emit paint or layout IR ids here and return them.
    // Library code that uses this path normally works directly with
    // fission_core::internal lowering helpers.
    Vec::new()
});

This is intentionally an advanced shape. The public app-authoring path remains impl From<Component> for Widget; canvas(...) is not a replacement component API.

Field table

Field	Type	Meaning	Notes / default behavior
width	Option<f32>	Fixed width of the canvas box.	None leaves width to the parent constraints.
height	Option<f32>	Fixed height of the canvas box.	None leaves height to the parent constraints.
painter	Fn(&mut InternalLoweringCx) -> Vec<WidgetId>	Closure that emits child IR ids to group inside the canvas box.	Required. This is an advanced lowering hook, not normal app authoring.

Behavior and advice

canvas(...) is still descriptive. The closure runs during lowering and should not start network work, mutate product state, spawn tasks, or touch host APIs. It should emit deterministic IR for the current inputs.

The helper does not automatically add semantics. If the visual surface communicates meaning, wrap it in surrounding widgets that provide labels or interaction. If the surface needs custom hit testing, event handling, input method editor behavior, or runtime painting, use CustomWidget and document the custom behavior carefully.

Treat canvas(...) as an advanced library escape hatch. It should not appear in ordinary examples that teach application structure.

Production checklist

For canvas, review the fields that change behavior before treating the widget as finished: width, height, painter. The goal is to make the product rule visible in state and actions, not hidden inside ad-hoc construction code.

•

If this widget appears inside an interactive flow, keep the surrounding action binding in the parent component and test that the flow still has one clear reducer path.

•

Check the semantics tree for the user-facing label or role that makes this widget understandable without relying only on pixels.

•

Prefer parent layout and design-system sizing first; use explicit size or spacing fields when the product layout requires that constraint on this widget specifically.

•

Add at least one component or harness test that confirms the visible text, semantic role, action dispatch, and layout constraint that matter for this widget in context.

If a screen starts repeating the same canvas setup, extract a named component around this widget. That keeps the reference API small while making product code easier to read and safer for generated code to copy.

CanvasLowerer, CustomWidget, Composite, and Container.