Textarea · Tinyrack Design System

테마가 적용된 테두리와 상태로 여러 줄 텍스트를 입력받아요.

핵심 속성

속성	설명
값	제어되지 않는 초기 상태에는 `initialValue`를, 화면이 텍스트를 직접 관리할 때는 `controller`를 넘기세요. 둘을 함께 주면 `assert`가 걸려요. `onChanged`는 값 소유권을 가져가지 않고 편집만 알려줘요.
크기	`uiSize`가 컨트롤 타이포그래피와 좌우 패딩을 정하고, 상자는 해당 사이즈 컨트롤 높이의 두 배를 최소 높이로 유지해요. 시작 높이는 `minLines`(기본값 `2`)로 정하고, `maxLines`는 지정하지 않아서 줄이 늘어나면 상자가 아래로 늘어나요. 웹 컨트롤과 달리 크기 조절 핸들은 없어요.
상태	`enabled: false`는 비활성 불투명도 토큰을 적용하고, `readOnly: true`는 muted 표면 위에서 텍스트를 선택할 수 있게 남겨둬요. 둘 다 hover 시 테두리가 진해지지 않게 해요. 포커스를 받으면 테두리가 focus 색과 더 두꺼운 포커스 테두리 두께로 바뀌어요.
폼	`name`을 지정하면 가장 가까운 `TRForm`에 등록돼 텍스트가 `TRFormState.values`와 `save()` 결과에 들어가요. 다만 `TRTextField`와 달리 `FormField`가 아니라서 `validator`를 쓸 수 없고 `TRFormState.reset()`도 텍스트를 되돌리지 않아요. 제출 핸들러에서 직접 검증하고, 메시지는 `TRField(errorText:)`로 보여주고, 텍스트는 직접 소유한 `controller`로 되돌리세요.
프레임	`solid`는 테두리와 배경을 직접 그려요. `ghost`는 평상시에만 둘 다 없애서 `TRCard` 컴포저처럼 감싸는 표면이 프레임을 소유하게 해요. hover와 포커스는 textarea가 계속 직접 그리니 표면이 대신 처리하지 않아도 되고, 테두리 박스는 같은 두께로 유지되어 appearance를 바꿔도 필드가 움직이지 않아요. `plain`은 hover와 포커스까지 넘겨요. 감싸는 표면이 그룹 전체의 포커스를 보여 줄 때 쓰세요.
레이블	`TRTextarea`는 자체 레이블을 그리지 않아요. 보이는 레이블이나 설명, 오류 메시지를 붙이려면 `TRField`로 감싸세요. `placeholder`는 placeholder 텍스트 색으로 표시되는 힌트라 첫 글자를 입력하면 사라지므로 레이블을 대신할 수 없어요.

TRTextarea는 TRTextField의 여러 줄 버전이에요. 짧은 값 하나가 아니라 메모나 설명을 받을 때 쓰세요.

설치

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

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

TRField(
  label: 'Rack notes',
  control: TRTextarea(
    name: 'notes',
    placeholder: 'Operational notes',
    onChanged: setNotes,
  ),
)

예시

운영 메모 고유 링크

TRField로 감싸 메모에 보이는 레이블을 붙이고, placeholder는 레이블 대신 어떤 내용을 적을지 안내하는 데 쓰세요.

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

편집 가능, 읽기 전용, 비활성 고유 링크

메모를 읽고 선택할 수 있게 남겨야 하면 readOnly를, 아예 쓸 수 없다면 enabled: false를 사용하세요. 레이블과 컨트롤을 맞추려면 같은 상태를 TRField에도 넘기세요.

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

보통과 크게 고유 링크

uiSize는 타이포그래피와 좌우 패딩을 바꾸고, 최소 높이는 해당 컨트롤 높이에서 정해져요. 밀도가 높은 화면에는 md를, 긴 글을 편집할 때는 lg를 고르세요.

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

폼 값과 수동 초기화 고유 링크

name을 지정한 textarea는 TRFormState.values에 나타나요. FormField가 아니라서 reset()으로는 텍스트가 그대로 남으니, 원래 메모는 직접 소유한 controller로 되돌리세요.

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

필수 입력 검증과 복구 고유 링크

TRTextarea에는 required나 validator 속성이 없어요. 제출할 때 텍스트를 확인하고 문제는 TRField(errorText:)로 알리며, focusNode로 포커스를 되돌려 바로 고칠 수 있게 하세요.

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

API

TRTextarea 속성

Prop	타입 / 기본값	용도
`controller`	`TextEditingController? · null`	위젯 바깥에서 텍스트를 소유해요. `initialValue`와 함께 쓸 수 없고, dispose는 호출한 쪽이 책임져요.
`initialValue`	`String? · null`	내부 컨트롤러를 한 번만 채워요. 이후 인자를 바꿔도 이미 입력된 텍스트를 덮어쓰지 않아요.
`placeholder`	`String? · null`	입력이 비어 있는 동안 placeholder 텍스트 색으로 힌트를 보여줘요.
`onChanged`	`ValueChanged<String>? · null`	편집할 때마다 현재 텍스트와 함께 호출돼요.
`name`	`String? · null`	가장 가까운 `TRForm`에 이 키로 값을 등록해요. 비활성 필드는 수집된 값에서 빠지고, `reset()`은 텍스트를 되돌리지 않아요.
`uiSize`	`TRUiSize · TRUiSize.md`	글자 크기와 좌우 패딩, 그리고 최소 상자 높이의 기준이 되는 컨트롤 높이를 정해요.
`minLines`	`int · 2`	상자가 늘어나기 전에 보여줄 줄 수를 정해요. 실제 높이는 현재 `uiSize`의 컨트롤 높이 두 배 아래로 내려가지 않아요.
`enabled`	`bool · true`	편집과 포커스를 막고 비활성 불투명도 토큰을 적용하며, 폼 값에서 해당 필드를 제외해요.
`readOnly`	`bool · false`	muted 표면 위에서 텍스트를 포커스하고 선택할 수는 있지만 편집은 못 하게 해요. 값은 그대로 폼에 전달돼요.
`autofocus`	`bool · false`	Textarea가 처음 마운트될 때 포커스를 요청해요. 메모 입력이 화면을 연 유일한 이유일 때만 쓰세요.
`focusNode`	`FocusNode? · null`	외부 포커스 노드를 넘겨 제출 실패 후처럼 화면이 Textarea로 포커스를 옮길 수 있게 해요.
`appearance`	`TRFieldAppearance · solid`	테두리가 있는 기본 컨트롤, 평상시 테두리와 배경을 없애 상위 표면이 감쌀 수 있게 하면서도 hover와 포커스는 직접 그리는 `ghost`, 포커스까지 그 표면에 맡기는 `plain` 중 하나를 선택해요.