Autocomplete · Tinyrack Design System

타입이 있는 정적 또는 비동기 제안으로 자유 텍스트 입력을 완성해요.

핵심 속성

속성	설명
값	검색어는 자유 형식 텍스트로 유지돼요. 제안을 선택하면 controller에 타입이 있는 값도 함께 저장돼요.
제안	정적 `items`를 전달하거나 `optionsBuilder`로 비동기 제안을 불러오세요. 이전 요청의 늦은 응답은 버려요.
상호작용	마우스를 올려도 입력 포커스를 유지해요. 방향키는 강조 항목을 옮기고 Enter는 선택하며, Escape는 닫고 Tab은 선택 없이 다음으로 이동해요.
레이어 크기	`layerSize`로 제안 레이어 전체 크기를 정해요. 기본 너비는 필드에 맞추고, 높이는 콘텐츠에 따라 `TRMeasurements.measureXl`까지 커져요.

설치

패키지를 추가한 뒤 공개 라이브러리를 가져오세요.

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';

TRAutocomplete<String>(
  label: 'Region',
  placeholder: 'Search regions',
  items: const [
    TRAutocompleteItem(value: 'seoul', label: 'Seoul'),
    TRAutocompleteItem(value: 'tokyo', label: 'Tokyo'),
  ],
  onSelected: (region) => selectedRegion = region,
)

예시

완성 모드 고유 링크

제안 목록, 인라인 완성, 두 동작 함께 사용, manual 모드 중에서 선택하세요. manual 모드는 텍스트를 입력하기 전까지 빈 검색어 목록을 표시하지 않아요.

Flutter 미리보기를 불러오는 중이에요

비동기 제안 고유 링크

optionsBuilder에서 Future를 반환해 원격 제안을 불러오세요. 요청 완료 순서가 바뀌어도 최신 검색어만 팝업을 업데이트해요.

Flutter 미리보기를 불러오는 중이에요

크기와 상태 고유 링크

uiSize로 주변 컨트롤과 높이를 맞추고 disabled, read-only, 오류 입력 상태를 알맞게 표시하세요.

Flutter 미리보기를 불러오는 중이에요

Controller 생명 주기 고유 링크

다른 컨트롤에서 검색어를 읽거나 필드를 지우고 타입이 있는 선택 값을 확인해야 한다면 TRAutocompleteController를 소유하세요. 소유한 State와 함께 dispose하세요.

Flutter 미리보기를 불러오는 중이에요

폼 검증 고유 링크

TRAutocompleteFormField는 검색어를 계속 편집할 수 있게 유지하면서 타입이 있는 선택 값을 Form 검증과 저장 콜백에 전달해요.

Flutter 미리보기를 불러오는 중이에요

포인터와 키보드 고유 링크

입력 포커스를 옮기지 않고 제안에 마우스를 올릴 수 있어요. 방향키로 강조하고 Enter로 선택하며, Escape로 닫고 Tab으로 선택 없이 이동하세요.

Flutter 미리보기를 불러오는 중이에요

API

제안

Prop	타입 / 기본값	용도
`items`	`List<TRAutocompleteItem<T>> = const []`	타입이 있는 정적 제안을 제공해요. 비활성 항목은 결과에서 제외돼요.
`optionsBuilder`	`FutureOr<Iterable<TRAutocompleteItem<T>>> Function(String)?`	현재 검색어로 제안을 불러와요. 동기 또는 비동기로 반환할 수 있어요.
`completionMode`	`TRAutocompleteCompletionMode = list`	`manual`, `list`, `inline`, `both` 완성 동작 중 하나를 선택해요.
`TRAutocompleteItem`	`value, label, enabled = true, leading?, trailing?`	타입이 있는 값에 레이블과 선택적 표현 요소를 연결해요.

상태와 콜백

Prop	타입 / 기본값	용도
`controller`	`TRAutocompleteController<T>?`	`query`와 `value`를 관찰하고 `select`나 `clear`를 호출하며 소유한 텍스트·포커스 controller를 dispose해요.
`onQueryChange`	`ValueChanged<String>?`	자유 텍스트 편집을 알려줘요.
`onSelected`	`ValueChanged<T>?`	제안에서 선택한 타입이 있는 값을 알려줘요.

필드와 폼

Prop	타입 / 기본값	용도
`enabled, readOnly`	`bool = true, bool = false`	상호작용을 비활성화하거나 포커스 가능한 읽기 전용 검색어를 유지해요.
`label, placeholder, helperText, errorText`	`String?`	필드와 검증 상태를 설명해요.
`uiSize, width`	`TRUiSize = md, double?`	컨트롤 크기와 선택적 고정 필드 너비를 정해요.
`layerSize`	`TRLayerSize · match anchor / content height ≤ measureXl`	필드 너비와 별도로 제안 레이어 전체 크기를 정해요.
`TRAutocompleteFormField`	`FormField<T>`	타입이 있는 선택 값으로 검증과 저장 콜백에 참여해요.