인라인 제안 · 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`	접히지 않는 세 가지 안내 행의 문구예요. 패키지에 로컬라이제이션 델리게이트가 없어서 호출하는 쪽이 제공해요.

TRInlineSuggestionItem 속성

Prop	타입 / 기본값	용도
`value · label`	`T · String`	선택 시 돌려주는 값과 행의 기본 텍스트예요.
`description · hint · tag`	`String? · null`	흐린 둘째 줄, 기대하는 인자 같은 뒤쪽 표시, 짧은 분류 칩이에요.
`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()`	하이라이트된 행을 확정하고 무언가 확정됐는지 알려주거나, 다음 세션까지 목록을 감춰요.