Read page as text

NIB / DOCUMENTATION

Accessibility and motion — NibGenUI

Use trusted labels and test real input, focus, and reduced-motion behavior.

Open interactive view

Own fallback text in the host

NibGeneratedSurfaceLabels supplies fallback text for empty, loading, error, invalid-tree, unsupported-component, action, and text-field states. Translate these in the host. The renderer cannot derive trustworthy accessible instructions from an unregistered wire component.

Only initial loading and error fallbacks are live regions. Bound text changes are not announced on every stream update.

APITypeDefaultBehavior
NibGeneratedSurfaceLabels.emptyStringNo generated contentShown before a surface exists.
NibGeneratedSurfaceLabels.errorStringUnable to load contentInitial load failure label when error is supplied.
NibGeneratedSurfaceLabels.unsupportedComponentStringUnsupported componentSafe fallback when the schema has no renderer builder.
NibGeneratedSurfaceLabels.textFieldStringText fieldFallback field name.

Provide language and layout around the surface

Start with the fixture rendering inside MaterialApp and a normally constrained page. The host supplies Flutter theme, text direction and text scaling. The generated data describes only the supported component fields; this Basic slice does not accept arbitrary accessibility attributes from a sender. Trusted builders and host fallback labels therefore carry the accessible behavior.

Place this widget where the generated surface belongs and replace each fallback string with your app’s translation. Empty means the surface does not exist yet. Loading covers incomplete content. Error is used for initial failure when the error argument is supplied and there is no valid surface. A later rejected frame should leave valid content visible and report its problem through host feedback rather than replacing the form with a generic error.

NibGeneratedSurface(
  runtime: runtime,
  surfaceId: 'main',
  motionEnabled: false,
  labels: const NibGeneratedSurfaceLabels(
    empty: 'Your form will appear here',
    loading: 'Preparing your form',
    error: 'The form could not load',
    invalidTree: 'The form structure could not be shown',
    unsupportedComponent: 'This control is unavailable',
    action: 'Continue',
    textField: 'Response',
  ),
)

Check focus after updates

The renderer keys nodes by runtime, surface, generation, and node ID. A bound TextField keeps its selection through local updates and clamps it after a shorter remote value. Surface deletion or replacement changes generation and should be treated as a new focus context.

Test keyboard traversal, screen readers, large text, and right-to-left direction in the host. Widget tests show part of the contract; physical assistive-technology behavior remains a separate release check.

Walk a progressively built form with the keyboard

Replay the website fixture one frame at a time. Before the root and data arrive, observe the fallback instead of expecting an editable completed form. After the third frame, reach Your name with Tab, type a value and activate Say hello from the keyboard. Confirm that the feedback is visible and that focus remains useful. Replay creates a new runtime, so treating it as a new focus context is appropriate.

Stable node IDs allow the renderer to preserve a field’s widget state across ordinary updates. Replacing IDs for every keystroke discards that continuity. Deleting and recreating a surface represents a new generation even when its external name is reused. Decide where focus should go after such a replacement; do not assume a stale focused node still exists.

Only initial loading and error fallbacks are live regions. Streaming text is not announced after every update, which avoids a constantly speaking interface, but it means important host results need deliberate accessible feedback. Do not hide submission success in color or movement alone. Give validation feedback a readable message and a route back to the field that needs correction.

Compare the surface with motionEnabled false and with the platform’s reduced-motion preference enabled. Both should keep the final content and actions usable without structural animation. Then test large text, a narrow viewport and right-to-left direction. Inspect custom builders too: a trusted builder can still have a fixed-size label or poor semantics. Widget tests cover important structure, but an actual screen reader and keyboard on each supported platform are needed to assess the complete task.

Turn off structural motion when needed

motionEnabled defaults to true, but the renderer also watches NibMotionConfig reduced motion and skips structural animation when it is active. A host can set motionEnabled: false for a surface that should update without movement.

Keep action outcomes and form errors visible without relying on animation. Theme and text direction come from the surrounding Flutter app.

APITypeDefaultBehavior
motionEnabledbooltrueStructural transitions when reduced motion is not active.
labelsNibGeneratedSurfaceLabelsEnglish defaultsHost-provided fallback copy.