Inline Suggestions · Tinyrack Design System

Offer suggestions for the token being typed inside a text field the caller owns.

Contract

Axis	Contract
Ownership	The caller keeps its own field, controller, and focus node, and passes them as `child`. This component never builds or reads the field, so a multiline editor keeps every property it already had.
Keyboard	A multiline editor consumes the arrow and enter keys itself, so the host calls `controller.handleKeyEvent` first inside its own handler. Keyboard and controller navigation keep the highlighted row in view. Anything the list does not consume comes back as `KeyEventResult.ignored`, which leaves Enter-to-send intact. A held modifier is never consumed, so Shift+Enter and Control+Enter stay with the field.
Session	`sessionKey` identifies the token being completed. Changing it resets the highlight and clears an earlier dismissal, so Escape hides the current token while a freshly typed one reopens. Results that arrive late for the same session keep the highlighted value rather than its index.
Status	Emptiness is derived from a ready list with no items, so a caller cannot describe a contradictory state. A loading list that still holds results keeps them on screen with a spinner below, which is what stops the list flickering on every keystroke.
Matching	The caller filters, orders, and scores; this component only renders. `matchedIndices` names the characters of `label` to emphasise, so a consumer highlights a match without naming a color.

Reach for inline suggestions when only part of what someone is typing should be completed, such as a mention or a command in a longer message. Use TRAutocomplete when the whole field is the query, and TRCombobox when the committed value must come from a list.

Install

Add the package, then import its public library.

flutter pub add tinyrack_ui

import 'package:tinyrack_ui/tinyrack_ui.dart';

Playground

Loading the Flutter preview

Usage

import 'package:material_ui/material_ui.dart';
import 'package:tinyrack_ui/tinyrack_ui.dart';

TRInlineSuggestions<String>(
  open: trigger != null,
  sessionKey: trigger?.start,
  controller: suggestions,
  items: matches,
  onSelected: (item) => complete(item.value),
  child: Focus(
    onKeyEvent: (node, event) => suggestions.handleKeyEvent(event),
    child: TRTextField(controller: text, maxLines: 8, minLines: 1),
  ),
)

API

TRInlineSuggestions properties

Prop	Type / default	Purpose
`child`	`Widget`	The field the caller owns, used verbatim as the trigger and as the position and width anchor.
`items`	`List<TRInlineSuggestionItem<T>>`	Rows to offer, already filtered and ordered by the caller.
`open`	`bool`	Whether a token is being completed. Fully controlled, because the condition depends on caret state this component cannot observe.
`sessionKey`	`Object? · null`	Identity of the token being completed; changing it resets the highlight and clears a dismissal.
`onSelected`	`ValueChanged<TRInlineSuggestionItem<T>>`	Reports the committed row. The caller performs the text edit with its own offsets.
`status`	`TRInlineSuggestionsStatus · ready`	Whether the list is settled, still loading, or failed.
`placement`	`TRLayerPlacement · topStart`	Where the list sits relative to the field; it flips when space runs out.
`layerSize`	`TRLayerSize · match anchor / content height ≤ measureXl`	Sizes the complete suggestion layer. The row-count limit may make the scrolling list shorter than a larger fixed or minimum layer height.
`maxVisibleItems`	`int · 8`	Rows shown before the list scrolls, counted rather than measured so the height follows the reader text size.
`autoHighlight`	`bool · true`	Arms the first row so Enter commits without pressing an arrow key first.
`acceptOnEnter · acceptOnTab`	`bool · true`	Whether Enter and Tab commit the highlighted row. Both are separate so a host can leave Enter to sending.
`emptyLabel · loadingLabel · errorLabel`	`String`	Copy for the three non-collapsing notice rows, supplied by the caller because the package carries no localization delegate.

TRInlineSuggestionItem properties

Prop	Type / default	Purpose
`value · label`	`T · String`	The payload handed back on selection and the primary row text.
`description · hint · tag`	`String? · null`	A muted second line, a trailing affordance such as expected arguments, and a short category chip.
`matchedIndices`	`List<int> · const []`	Characters of `label` to emphasise. The caller owns the matcher; the design system owns the emphasis.
`enabled`	`bool · true`	A disabled row stays visible, renders muted, and is skipped by keyboard navigation and commit.

TRInlineSuggestionsController members

Prop	Type / default	Purpose
`handleKeyEvent`	`KeyEventResult Function(KeyEvent)`	Call this first inside the host field `Focus(onKeyEvent:)`; `ignored` means the host still owns the key.
`isOpen · highlightIndex · highlightedItem`	`bool · int · TRInlineSuggestionItem<T>?`	Reads the live list state; `highlightIndex` is -1 when nothing is armed.
`highlightNext · highlightPrevious · highlightFirst · highlightLast`	`void Function()`	Moves the highlight, wrapping at each end and skipping disabled rows.
`commitHighlighted · dismiss`	`bool Function() · void Function()`	Commits the highlighted row, reporting whether anything was committed, or hides the list until the next session.