インライン候補 · Tinyrack Design System

呼び出し側が所有するテキストフィールドで入力中のトークンに候補を提示します。

主なプロパティ

プロパティ	説明
所有	呼び出し側がフィールド、controller、focus node をそのまま所有し、`child` として渡します。このコンポーネントはフィールドを構築も参照もしないため、複数行エディタの既存のプロパティはすべて保たれます。
キーボード	複数行エディタは矢印キーと Enter キーを自身で消費するため、ホストは自分のハンドラ内でまず `controller.handleKeyEvent` を呼びます。キーボードまたは controller で移動すると、ハイライト中の行が表示範囲内に保たれます。リストが消費しなかったキーは `KeyEventResult.ignored` として返るので、Enter での送信はそのまま機能します。修飾キーを伴う組み合わせは決して消費しないため、Shift+Enter と Control+Enter はフィールドに残ります。
セッション	`sessionKey` は補完中のトークンを識別します。値が変わるとハイライトが初期化され、以前の非表示も解除されるため、Escape は現在のトークンだけを隠し、新しく入力したトークンでは再び開きます。同じセッションに遅れて届いた結果は、インデックスではなくハイライト中の値を保持します。
状態	空の状態は項目のない ready のリストから導かれるため、矛盾した状態を表現できません。すでに結果を持つ loading のリストはその結果を画面に残し、下にスピナーを表示します。これがキー入力ごとのちらつきを防ぎます。
マッチング	フィルタリング、並べ替え、スコア付けは呼び出し側が行い、このコンポーネントは描画のみを担当します。`matchedIndices` は強調する `label` の文字を指すため、利用側は色を指定せずに一致箇所を強調できます。

メンションやコマンドのように、長い文章の一部だけを補完したい場合に inline suggestions を使ってください。フィールド全体が検索語なら TRAutocomplete を、確定値が必ず一覧から選ばれる必要があるなら TRCombobox を使ってください。

インストール

パッケージを追加し、公開ライブラリをインポートしてください。

flutter pub add tinyrack_ui

import 'package:tinyrack_ui/tinyrack_ui.dart';

プレイグラウンド

Flutter プレビューを読み込んでいます

使用方法

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 のプロパティ

Prop	型 / デフォルト	用途
`child`	`Widget`	呼び出し側が所有するフィールドです。トリガーとして、また位置と幅の基準としてそのまま使われます。
`items`	`List<TRInlineSuggestionItem<T>>`	呼び出し側が既にフィルタリングし並べ替えた、提示する行です。
`open`	`bool`	トークンを補完中かどうかです。このコンポーネントからは観測できないキャレットの状態に依存するため、完全な制御型です。
`sessionKey`	`Object? · null`	補完中のトークンの識別子です。値が変わるとハイライトが初期化され、非表示も解除されます。
`onSelected`	`ValueChanged<TRInlineSuggestionItem<T>>`	確定した行を通知します。テキストの編集は呼び出し側が自身のオフセットで行います。
`status`	`TRInlineSuggestionsStatus · ready`	リストが確定済みか、読み込み中か、失敗したかを表します。
`placement`	`TRLayerPlacement · topStart`	フィールドを基準としたリストの配置です。余白が足りない場合は反対側へ反転します。
`layerSize`	`TRLayerSize · match anchor / content height ≤ measureXl`	候補レイヤー全体のサイズを指定します。より大きい固定高さや最小高さを指定しても、行数の上限によりスクロールリスト自体はそれより短くなる場合があります。
`maxVisibleItems`	`int · 8`	スクロールが始まるまでに表示する行数です。ピクセルではなく個数のため、高さは読み手の文字サイズに追従します。
`autoHighlight`	`bool · true`	最初の行をあらかじめ選択し、矢印キーを押さずに Enter で確定できるようにします。
`acceptOnEnter · acceptOnTab`	`bool · true`	Enter と Tab がハイライト行を確定するかどうかです。両者を分けることで、ホストは Enter を送信専用に残せます。
`emptyLabel · loadingLabel · errorLabel`	`String`	折りたたまれない 3 種類の通知行の文言です。パッケージにローカライズのデリゲートがないため、呼び出し側が指定します。

TRInlineSuggestionItem のプロパティ

Prop	型 / デフォルト	用途
`value · label`	`T · String`	選択時に返されるペイロードと、行の主テキストです。
`description · hint · tag`	`String? · null`	淡い 2 行目、想定される引数などの末尾表示、短い分類チップです。
`matchedIndices`	`List<int> · const []`	強調する `label` の文字です。マッチングは呼び出し側が、強調表現はデザインシステムが担います。
`enabled`	`bool · true`	無効な行は表示されたまま淡く描画され、キーボード移動と確定の双方でスキップされます。

TRInlineSuggestionsController のメンバー

Prop	型 / デフォルト	用途
`handleKeyEvent`	`KeyEventResult Function(KeyEvent)`	ホストフィールドの `Focus(onKeyEvent:)` 内で最初に呼び出します。`ignored` の場合、そのキーは引き続きホストのものです。
`isOpen · highlightIndex · highlightedItem`	`bool · int · TRInlineSuggestionItem<T>?`	現在のリスト状態を読み取ります。何も選択されていない場合、`highlightIndex` は -1 です。
`highlightNext · highlightPrevious · highlightFirst · highlightLast`	`void Function()`	ハイライトを移動します。両端で循環し、無効な行はスキップします。
`commitHighlighted · dismiss`	`bool Function() · void Function()`	ハイライト行を確定して何かが確定されたかを返すか、次のセッションまでリストを非表示にします。