PlTextField

한 줄 또는 여러 줄 텍스트 입력입니다. 라벨과 보조 설명, 오류 메시지가 직접 엮어야 하는 세 요소가 아니라 컴포넌트의 일부입니다.

React

import { PlTextField } from 'plass-ui';

<PlTextField label="Email" type="email" description="We never share it." />;

import 'package:plass_ui/plass_ui.dart';

PlTextField(
  controller: email,
  label: const Text('Email'),
  keyboardType: TextInputType.emailAddress,
  description: const Text('We never share it.'),
);

Props

Prop	타입	기본값	설명
variant공통	'solid' | 'glass' | 'ghost'	'glass'	표면의 재질. 필드에서 solid는 색 유리판이 아니라 시트에 파인 우물입니다 — 필드가 담는 것은 사용자 데이터입니다
size공통	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	높이와 타입 스케일. PlButton과 같은 높이라서 한 줄에 섞어 놓아도 기준선이 맞습니다
color공통	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	의미론적 색 역할. 유리는 물들이지 않으므로 가장자리와 포커스 링, 캐럿에만 나타납니다
density공통	'default' | 'compact'	'default'	여백만 바꿉니다. 높이와 글자 크기는 그대로
elevation공통	0 | 1 | 2 | 3	0	그림자 깊이. 필드는 떠 있는 표면이 아니라 파인 자리이므로 기본값이 0입니다
label	ReactNode	—	컨트롤 위 라벨. Base UI Field로 연결됩니다
description	ReactNode	—	컨트롤 아래 보조 설명
error	ReactNode	—	컨트롤 아래 오류 메시지. 값이 있으면 invalid 상태도 함께 켜집니다
invalid	boolean	!!error	메시지 없이 invalid만 켭니다. 외부 폼 라이브러리가 유효성을 가질 때
multiline	boolean	false	input 대신 textarea로 렌더링합니다. 나머지 축은 그대로
rows	number	3	multiline일 때 보이는 줄 수
resize	'none' | 'vertical' | 'horizontal' | 'both'	'vertical'	multiline을 사용자가 어느 방향으로 늘릴 수 있는지. 가로로 늘리면 폼의 열이 깨지므로 세로만 기본값입니다
startIcon	ReactNode	—	컨트롤 앞에 놓이는 내용. 1.2em으로 그려져 글자 크기를 따라갑니다
endIcon	ReactNode	—	컨트롤 뒤에 놓이는 내용
loading	boolean	false	endIcon 자리에 스피너를 띄우고 busy로 표시합니다. 입력은 계속 가능합니다
readOnly	boolean	false	값은 읽고 복사할 수 있지만 고쳐 쓸 수는 없습니다. 채도가 빠지고 평평해집니다
disabled	boolean	false	사용 불가. 시트 너머로 페이지가 비쳐 보이며, 포커스 순서에서 빠집니다
fullWidth	boolean	false	컨테이너 너비만큼 확장
hotKeys	Record<string, () => void>	—	이 컨트롤이 답할 chord들. PlHotKeys가 그리는 것과 같은 철자입니다 — { 'Mod+Enter': save, Escape: cancel }. 맞는 chord는 **소비됩니다**
classNames	{ label?, control?, description?, error?: string }	—	className이 닿지 않는 부분에 붙는 class. control은 실제로 조작하는 부분입니다

Prop	타입	기본값	설명
controller	TextEditingController?	—	편집 중인 텍스트. Flutter가 텍스트를 두는 자리입니다. 빼면 필드가 하나를 스스로 만듭니다
onChanged	ValueChanged<String>?	—	모든 변화를 알립니다
onSubmitted	ValueChanged<String>?	—	키보드에서 제출했을 때
variant공통	PlassVariant	PlassVariant.solid	표면의 재질. 필드에서 solid는 색 유리판이 아니라 시트에 파인 우물입니다 — 필드가 담는 것은 사용자 데이터입니다
size공통	PlassSize	PlassSize.md	높이와 타입 스케일. PlButton과 같은 높이라서 한 줄에 섞어 놓아도 기준선이 맞습니다
color공통	PlassColor	PlassColor.primary	의미론적 색 역할. 유리는 물들이지 않으므로 가장자리와 포커스 링, 캐럿에만 나타납니다
density공통	PlassDensity	PlassDensity.standard	여백만 바꿉니다. 높이와 글자 크기는 그대로
elevation공통	int	0	그림자 깊이. 필드는 떠 있는 표면이 아니라 파인 자리이므로 기본값이 0입니다
multiline	bool	false	input 대신 textarea로 렌더링합니다. 나머지 축은 그대로
rows	int	3	multiline일 때 보이는 줄 수
label	Widget?	—	컨트롤 위 라벨. Base UI Field로 연결됩니다
description	Widget?	—	컨트롤 아래 보조 설명
error	Widget?	—	컨트롤 아래 오류 메시지. 값이 있으면 invalid 상태도 함께 켜집니다
invalid	bool?	!!error	메시지 없이 invalid만 켭니다. 외부 폼 라이브러리가 유효성을 가질 때
placeholder	String?	—	비어 있는 동안 보이는 것. React에서는 네이티브 속성이라 표에 없습니다
startIcon	Widget?	—	컨트롤 앞에 놓이는 내용. 1.2em으로 그려져 글자 크기를 따라갑니다
endIcon	Widget?	—	컨트롤 뒤에 놓이는 내용
loading	bool	false	endIcon 자리에 스피너를 띄우고 busy로 표시합니다. 입력은 계속 가능합니다
fullWidth	bool	false	컨테이너 너비만큼 확장
readOnly	bool	false	값은 읽고 복사할 수 있지만 고쳐 쓸 수는 없습니다. 채도가 빠지고 평평해집니다
disabled	bool	false	사용 불가. 시트 너머로 페이지가 비쳐 보이며, 포커스 순서에서 빠집니다
obscureText	bool	false	입력한 것을 가립니다. 비밀번호용
keyboardType	TextInputType?	—	터치 기기에서 올릴 키보드
maxLength	int?	—	받을 글자 수. 카운터가 아니라 formatter입니다 — 아래에 아무것도 그려지지 않습니다
semanticLabel	String?	—	보이는 label이 없는 필드를 스크린 리더가 부를 이름. placeholder는 이름이 아닙니다
hotKeys	PlassHotKeys?	—	이 컨트롤이 답할 chord들. PlHotKeys가 그리는 것과 같은 철자입니다 — { 'Mod+Enter': save, Escape: cancel }. 맞는 chord는 **소비됩니다**

네이티브 <input> 속성은 그대로 전달되고, multiline일 때는 <textarea> 속성이 그대로 전달됩니다. 예외는 위 공통 축과 이름이 겹치는 color와 size입니다.

className은 label과 control, 그 아래 두 줄을 함께 담는 stack에 붙습니다. 그 안쪽 네 부분에 닿는 것이 classNames입니다: label, control(글자가 들어가는 상자), description, error.

값은 TextEditingController에 삽니다. Flutter가 텍스트를 두는 자리가 거기입니다. 빼면 필드가 하나를 스스로 만들지만, 값이 앱에 필요한 필드라면 앱이 controller를 건네주어야 하는 필드입니다.

아래에 있는 것은 TextField가 아니라 EditableText입니다. 앞의 것은 Material이고, 이 패키지는 Material도 Cupertino도 가져오지 않습니다. Material이 그 위에 얹는 것(데코레이션, 카운터, 리플)이 바로 이 컴포넌트가 대신하는 것입니다.

공통 축이 라이브러리 전체에서 뜻하는 것은 prop 규칙에 있습니다.

Examples

variant

glass가 기본값입니다. hairline을 두른 시트이고, 그 선은 시트 자신의 흰 테두리가 아니라 --plass-border입니다. 필드는 대개 카드 위에 놓이는데, 흰 카드 위 거의 흰 상자에 흰 선을 두르면 모양이 보이지 않기 때문입니다. solid는 우물입니다. 가장 불투명한 유리에 라이브러리에서 유일한 inset 그림자가 얹힌 형태로, 파인 것처럼 보여야 하는 필드에 씁니다. ghost는 포인터가 올라오기 전까지 표면이 없어서 테이블 셀 안의 필드에 어울립니다.

solid 필드는 의도적으로 색 유리판이 아닙니다. 캐럿과 텍스트 선택, placeholder 아래에 깔린 그러데이션은 읽히지 않기 때문에, 색 계열은 대신 hairline과 focus ring, 캐럿에 나타납니다.

React

import { PlTextField } from 'plass-ui';

export default function TextFieldVariants() {
  return (
    <div className="grid w-full max-w-sm gap-4">
      <PlTextField variant="glass" label="glass" placeholder="A sheet with a hairline" />
      <PlTextField variant="solid" label="solid" placeholder="A well cut into the sheet" />
      <PlTextField variant="ghost" label="ghost" placeholder="No surface until you go near it" />
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class TextFieldVariants extends StatelessWidget {
  const TextFieldVariants({super.key});

  @override
  Widget build(BuildContext context) {
    return const SizedBox(
      width: 384,
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.stretch,
        mainAxisSize: MainAxisSize.min,
        spacing: 16,
        children: <Widget>[
          PlTextField(
            fullWidth: true,
            label: Text('glass'),
            placeholder: 'A sheet with a hairline',
          ),
          PlTextField(
            fullWidth: true,
            variant: PlassVariant.solid,
            label: Text('solid'),
            placeholder: 'A well cut into the sheet',
          ),
          PlTextField(
            fullWidth: true,
            variant: PlassVariant.ghost,
            label: Text('ghost'),
            placeholder: 'No surface until you go near it',
          ),
        ],
      ),
    );
  }
}

size

PlButton과 같은 사다리입니다. xs 24px · sm 32px · md 40px · lg 48px · xl 56px. 같은 size의 필드와 버튼은 한 줄에서 기준선이 맞습니다.

React

import { PlTextField } from 'plass-ui';

export default function TextFieldSizes() {
  return (
    <div className="grid w-full max-w-sm gap-4">
      <PlTextField size="xs" placeholder="Extra small" />
      <PlTextField size="sm" placeholder="Small" />
      <PlTextField size="md" placeholder="Medium" />
      <PlTextField size="lg" placeholder="Large" />
      <PlTextField size="xl" placeholder="Extra large" />
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class TextFieldSizes extends StatelessWidget {
  const TextFieldSizes({super.key});

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 384,
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.stretch,
        mainAxisSize: MainAxisSize.min,
        spacing: 16,
        children: <Widget>[
          for (final size in PlassSize.values)
            PlTextField(fullWidth: true, size: size, placeholder: size.name),
        ],
      ),
    );
  }
}

label, description, error

셋 다 노드이고, 셋 다 Base UI의 Field가 컨트롤과 연결해 줍니다. 라벨은 컨트롤을 가리키고, 두 메시지는 모두 컨트롤의 aria-describedby에 들어갑니다.

셋 다 위젯이고, 셋 다 필드 자신의 semantics 노드에 포함됩니다. 그래서 스크린 리더가 라벨과 필드와 메시지를 셋이 아니라 하나로 읽습니다.

floating label variant는 없습니다. floating label은 입력 중인 대상에 transform을 걸어야 하는데, 캐럿 아래에서 움직이는 라벨은 이 라이브러리가 컨트롤에 대해 유일하게 금지하는 효과입니다.

유효성

error는 메시지를 담는 동시에 필드를 invalid로 만들고, 그러면 slot 계열 전체가 danger로 넘어갑니다. hairline과 focus ring, 캐럿, 메시지가 한꺼번에 바뀝니다.

폼 라이브러리가 유효성을 가질 때를 위한 탈출구가 둘 있습니다. invalid는 메시지 없이 상태만 켜고, invalid={false}invalid: false는 상태 없이 메시지만 보여 줍니다.

React

import { useState } from 'react';
import { PlButton, PlTextField } from 'plass-ui';

export default function TextFieldValidation() {
  const [value, setValue] = useState('acme inc');
  const message = value.includes(' ') ? 'Spaces are not allowed.' : undefined;

  return (
    <div className="flex w-full max-w-sm items-end gap-3">
      <PlTextField
        fullWidth
        label="Workspace"
        value={value}
        error={message}
        description={message ? undefined : 'Letters, numbers and dashes.'}
        onChange={(event) => setValue(event.target.value)}
      />
      <PlButton disabled={Boolean(message)}>Create</PlButton>
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class TextFieldValidation extends StatefulWidget {
  const TextFieldValidation({super.key});

  @override
  State<TextFieldValidation> createState() => _TextFieldValidationState();
}

class _TextFieldValidationState extends State<TextFieldValidation> {
  final TextEditingController _workspace = TextEditingController(text: 'acme inc');
  String _value = 'acme inc';

  @override
  void dispose() {
    _workspace.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    final invalid = _value.contains(' ');

    return SizedBox(
      width: 384,
      child: Row(
        crossAxisAlignment: CrossAxisAlignment.end,
        spacing: 12,
        children: <Widget>[
          Expanded(
            child: PlTextField(
              fullWidth: true,
              controller: _workspace,
              label: const Text('Workspace'),
              onChanged: (String next) => setState(() => _value = next),
              error: invalid ? const Text('Spaces are not allowed.') : null,
              description: invalid ? null : const Text('Letters, numbers and dashes.'),
            ),
          ),
          PlButton(disabled: invalid, onPressed: () {}, child: const Text('Create')),
        ],
      ),
    );
  }
}

multiline

나머지 축은 완전히 동일하고, 한 줄짜리 여러 줄 필드는 같은 size의 한 줄 필드와 정확히 같은 높이입니다. 세로 여백이 높이 사다리에서 계산되기 때문에 density는 여기에 손대지 않습니다.

<textarea>를 렌더링합니다. resize는 사용자가 어느 방향으로 끌 수 있는지를 정합니다. 가로로 늘리면 폼의 열이 깨지므로 기본값은 세로 축만입니다.

resize는 없습니다. textarea의 크기 조절 손잡이는 브라우저의 것이고, Flutter에는 내놓을 대응물이 없습니다. 크기가 달라져야 하는 필드는 주변 레이아웃이 크기를 바꿔 주는 필드입니다.

React

import { PlTextField } from 'plass-ui';

export default function TextFieldMultiline() {
  return (
    <div className="grid w-full max-w-sm gap-4">
      <PlTextField multiline rows={1} label="One row" placeholder="Exactly a single-line field" />
      <PlTextField
        multiline
        label="Release note"
        rows={4}
        description="Markdown is not rendered here."
      />
      <PlTextField
        multiline
        resize="none"
        rows={2}
        label="Fixed"
        defaultValue="Cannot be dragged."
      />
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class TextFieldMultiline extends StatelessWidget {
  const TextFieldMultiline({super.key});

  @override
  Widget build(BuildContext context) {
    return const SizedBox(
      width: 384,
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.stretch,
        mainAxisSize: MainAxisSize.min,
        spacing: 16,
        children: <Widget>[
          PlTextField(
            fullWidth: true,
            multiline: true,
            rows: 1,
            label: Text('One row'),
            placeholder: 'Exactly a single-line field',
          ),
          PlTextField(
            fullWidth: true,
            multiline: true,
            rows: 4,
            label: Text('Release note'),
            description: Text('Markdown is not rendered here.'),
          ),
        ],
      ),
    );
  }
}

startIcon과 endIcon

행이 아니라 글자를 기준으로 크기가 정해집니다. 컨트롤 안이 아니라 shell에 붙으며 컨트롤의 focus에 반응합니다. 필드가 focus되면 adornment가 muted에서 accent 색으로 바뀝니다.

adornment는 컨트롤의 첫 줄을 기준으로 가운데 정렬되므로, multiline 필드가 늘어나도 자리를 지킵니다.

React

import { PlTextField } from 'plass-ui';

function SearchIcon() {
  return (
    <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.6" aria-hidden="true">
      <circle cx="7" cy="7" r="4.5" />
      <path d="m10.5 10.5 3 3" strokeLinecap="round" />
    </svg>
  );
}

export default function TextFieldIcons() {
  return (
    <div className="grid w-full max-w-sm gap-4">
      <PlTextField startIcon={<SearchIcon />} placeholder="Search projects" />
      <PlTextField label="Domain" defaultValue="acme" endIcon={<span>.plass.dev</span>} />
      <PlTextField label="Checking availability" defaultValue="acme" loading />
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

/// A magnifier, which is the whole glyph a search field needs.
class _SearchGlyph extends StatelessWidget {
  const _SearchGlyph();

  @override
  Widget build(BuildContext context) {
    final theme = IconTheme.of(context);

    return CustomPaint(
      size: Size.square(theme.size ?? 16),
      painter: _SearchPainter(theme.color ?? const Color(0xFF000000)),
    );
  }
}

class _SearchPainter extends CustomPainter {
  const _SearchPainter(this.color);

  final Color color;

  @override
  void paint(Canvas canvas, Size size) {
    final paint = Paint()
      ..style = PaintingStyle.stroke
      ..strokeWidth = 1.6
      ..strokeCap = StrokeCap.round
      ..color = color;

    canvas
      ..save()
      ..scale(size.shortestSide / 16)
      ..drawCircle(const Offset(7, 7), 4.5, paint)
      ..drawLine(const Offset(10.5, 10.5), const Offset(13.5, 13.5), paint)
      ..restore();
  }

  @override
  bool shouldRepaint(_SearchPainter oldDelegate) => oldDelegate.color != color;
}

class TextFieldIcons extends StatefulWidget {
  const TextFieldIcons({super.key});

  @override
  State<TextFieldIcons> createState() => _TextFieldIconsState();
}

class _TextFieldIconsState extends State<TextFieldIcons> {
  final TextEditingController _domain = TextEditingController(text: 'acme');
  final TextEditingController _checking = TextEditingController(text: 'acme');

  @override
  void dispose() {
    _domain.dispose();
    _checking.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 384,
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.stretch,
        mainAxisSize: MainAxisSize.min,
        spacing: 16,
        children: <Widget>[
          const PlTextField(
            fullWidth: true,
            startIcon: _SearchGlyph(),
            placeholder: 'Search projects',
          ),
          PlTextField(
            fullWidth: true,
            controller: _domain,
            label: const Text('Domain'),
            endIcon: const Text('.plass.dev'),
          ),
          PlTextField(
            fullWidth: true,
            controller: _checking,
            label: const Text('Checking availability'),
            loading: true,
          ),
        ],
      ),
    );
  }
}

loading · readOnly · disabled

prop	겉모습	입력	Focus
loading	endIcon 자리에 스피너	가능	유지
readOnly	색은 유지, 평평해지고 채도가 빠짐	불가, 선택은 가능	유지
disabled	시트 너머로 페이지가 비쳐 보임	불가	잃음

loading이 입력을 계속 허용하는 것은 의도된 것입니다. 필드가 로딩 중인 이유는 대개 거기에 입력된 내용 때문입니다.

React

import { PlTextField } from 'plass-ui';

export default function TextFieldStates() {
  return (
    <div className="grid w-full max-w-sm gap-4">
      <PlTextField label="Idle" placeholder="Type here" />
      <PlTextField label="Loading" defaultValue="acme-inc" loading />
      <PlTextField label="Read-only" defaultValue="acme-inc" readOnly />
      <PlTextField label="Disabled" defaultValue="acme-inc" disabled />
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class TextFieldStates extends StatefulWidget {
  const TextFieldStates({super.key});

  @override
  State<TextFieldStates> createState() => _TextFieldStatesState();
}

class _TextFieldStatesState extends State<TextFieldStates> {
  final List<TextEditingController> _filled = <TextEditingController>[
    TextEditingController(text: 'acme-inc'),
    TextEditingController(text: 'acme-inc'),
    TextEditingController(text: 'acme-inc'),
  ];

  @override
  void dispose() {
    for (final controller in _filled) {
      controller.dispose();
    }
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 384,
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.stretch,
        mainAxisSize: MainAxisSize.min,
        spacing: 16,
        children: <Widget>[
          const PlTextField(fullWidth: true, label: Text('Idle'), placeholder: 'Type here'),
          PlTextField(
            fullWidth: true,
            controller: _filled[0],
            label: const Text('Loading'),
            loading: true,
          ),
          PlTextField(
            fullWidth: true,
            controller: _filled[1],
            label: const Text('Read-only'),
            readOnly: true,
          ),
          PlTextField(
            fullWidth: true,
            controller: _filled[2],
            label: const Text('Disabled'),
            disabled: true,
          ),
        ],
      ),
    );
  }
}

hotKeys

Mod+Enter로 저장하고 Escape로 비우는 필드는 달리 둘 곳이 없는 키보드 어포던스입니다. hotKeys는 chord와 그 chord가 하는 일의 map이고, PlHotKeys가 그리는 것과 같은 vocabulary로 씁니다. 필드 옆에 찍힌 키캡과 실제로 동작하는 키가 문자열 하나에서 나오므로 서로 어긋날 수가 없습니다.

Mod는 platform에 따라 정해집니다. 항목 하나가 Mac에서는 ⌘, 그 밖에서는 Ctrl입니다. Esc, Return, Cmd, Option도 키캡과 같은 키로 접힙니다.

맞는 chord는 소비됩니다(handler가 실행되고 키는 더 이상 가지 않습니다. 그래서 여기 묶은 Escape는 필드를 감싼 dialog를 닫지 않고, Enter는 form을 제출하지 않습니다. 키를 묶는다는 것이 그런 뜻이고, 그래서 이건 글자가 아니라 chord여야 합니다) { a: … }는 a를 칠 수 없는 필드입니다.

React

import { useState } from 'react';
import { PlHotKeys, PlTextField } from 'plass-ui';

export default function TextFieldHotKeys() {
  const [note, setNote] = useState('');
  const [saved, setSaved] = useState<string | null>(null);

  return (
    <div className="flex w-full max-w-sm flex-col gap-4">
      <PlTextField
        fullWidth
        multiline
        rows={3}
        label="Note"
        placeholder="Write something, then press the shortcut"
        value={note}
        onChange={(event) => setNote(event.target.value)}
        description={
          <span className="flex items-center gap-1.5">
            <PlHotKeys keys="Mod+Enter" size="xs" /> to save, <PlHotKeys keys="Escape" size="xs" />{' '}
            to clear
          </span>
        }
        hotKeys={{
          'Mod+Enter': () => setSaved(note),
          Escape: () => {
            setNote('');
            setSaved(null);
          }
        }}
      />

      <p className="text-sm text-(--plass-muted-fg)">
        {saved === null ? 'Nothing saved yet.' : `Saved: ${saved}`}
      </p>
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class TextFieldHotKeys extends StatefulWidget {
  const TextFieldHotKeys({super.key});

  @override
  State<TextFieldHotKeys> createState() => _TextFieldHotKeysState();
}

class _TextFieldHotKeysState extends State<TextFieldHotKeys> {
  final TextEditingController _note = TextEditingController();
  String? _saved;

  @override
  void dispose() {
    _note.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 384,
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        mainAxisSize: MainAxisSize.min,
        spacing: 12,
        children: <Widget>[
          PlTextField(
            fullWidth: true,
            multiline: true,
            rows: 3,
            controller: _note,
            label: const Text('Note'),
            placeholder: 'Write something, then press the shortcut',
            description: const Row(
              mainAxisSize: MainAxisSize.min,
              spacing: 6,
              children: <Widget>[
                PlHotKeys(keys: 'Mod+Enter', size: PlassSize.xs),
                Text('to save,'),
                PlHotKeys(keys: 'Escape', size: PlassSize.xs),
                Text('to clear'),
              ],
            ),
            hotKeys: <String, VoidCallback>{
              'Mod+Enter': () => setState(() => _saved = _note.text),
              'Escape': () => setState(() {
                _note.clear();
                _saved = null;
              }),
            },
          ),
          PlTypography(
            _saved == null ? 'Nothing saved yet.' : 'Saved: $_saved',
            level: PlTypographyLevel.caption,
          ),
        ],
      ),
    );
  }
}

Controlled

value와 onChange는 네이티브 input에서와 똑같이 동작합니다. onChange는 두 요소를 모두 받도록 타입이 잡혀 있어서 multiline에서도 같은 핸들러가 그대로 쓰입니다.

controller가 곧 값이고, onChanged는 모든 변화를 알려줍니다. maxLength는 카운터가 아니라 formatter입니다. 스물다섯 번째 글자가 도착하지 못하게 막을 뿐, 직접 그리지 않는 한 필드 아래에는 아무것도 그려지지 않습니다.

React

import { useState } from 'react';
import { PlTextField } from 'plass-ui';

export default function TextFieldControlled() {
  const [value, setValue] = useState('');

  return (
    <div className="grid w-full max-w-sm gap-2">
      <PlTextField
        label="Display name"
        value={value}
        maxLength={24}
        placeholder="Ada Lovelace"
        onChange={(event) => setValue(event.target.value)}
      />
      <p className="text-xs text-(--plass-muted-fg)">{value.length}/24</p>
    </div>
  );
}

import 'package:flutter/widgets.dart';
import 'package:plass_ui/plass_ui.dart';

class TextFieldControlled extends StatefulWidget {
  const TextFieldControlled({super.key});

  @override
  State<TextFieldControlled> createState() => _TextFieldControlledState();
}

class _TextFieldControlledState extends State<TextFieldControlled> {
  final TextEditingController _name = TextEditingController();
  int _length = 0;

  @override
  void dispose() {
    _name.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      width: 384,
      child: Column(
        crossAxisAlignment: CrossAxisAlignment.start,
        mainAxisSize: MainAxisSize.min,
        spacing: 8,
        children: <Widget>[
          PlTextField(
            fullWidth: true,
            controller: _name,
            label: const Text('Display name'),
            placeholder: 'Ada Lovelace',
            maxLength: 24,
            onChanged: (String next) => setState(() => _length = next.length),
          ),
          PlTypography('$_length/24', level: PlTypographyLevel.caption),
        ],
      ),
    );
  }
}

Accessibility

• 네이티브 <input>을, multiline에서는 <textarea>를 렌더링합니다. 둘 다 각자의 요소가 받는 모든 속성을 받습니다.
• label은 컨트롤을 가리키는 실제 <label>입니다. 라벨이 없다면 aria-label을 주거나, placeholder가 유일한 이름이 되지 않게 하세요.
• description과 error는 모두 aria-describedby에 들어가므로, 스크린 리더가 메시지를 필드 뒤가 아니라 필드와 함께 읽습니다.
• error와 invalid는 aria-invalid를 설정합니다.
• focus ring은 컨트롤이 아니라 shell에 그려져서, 안쪽에 떠 있는 사각형이 아니라 유리의 가장자리를 따라갑니다. :focus-visible에서만 나타납니다.
• shell의 여백을 클릭하면 네이티브 input 안을 클릭했을 때처럼 캐럿이 필드로 들어갑니다.

• 텍스트 필드로 알려지고, 읽기 전용이거나 사용할 수 없을 때는 그렇게 알려집니다.
• 라벨과 필드, 설명, 메시지는 하나의 semantics 노드입니다. 그래서 스크린 리더가 차례로가 아니라 함께 읽습니다. 보이는 라벨이 없다면 semanticLabel을 주세요. placeholder는 이름이 아닙니다.
• focus ring은 편집기가 아니라 shell에 그려져서, 안쪽에 떠 있는 사각형이 아니라 유리의 가장자리를 따라갑니다. CSS가 :focus-visible이라고 부르는 것에서만 나타납니다.
• shell의 여백을 누르면 네이티브 input 안을 눌렀을 때처럼 캐럿이 필드로 들어갑니다.
• 선택은 드래그로 하고, 그 뒤에 조절할 손잡이는 없습니다. 터치 플랫폼이 선택 아래에 붙이는 드래그 손잡이는 Material과 Cupertino의 것이고, 이 패키지는 둘 다 가져오지 않습니다.

React 빌드와 다른 점

React	Flutter	이유
value / onChange	controller / onChanged	TextEditingController가 Flutter가 텍스트를 두는 자리이고, 호출자가 이미 들고 있는 것입니다.
type="email"	keyboardType	어떤 키보드를 올릴지 말하는 Flutter의 방식입니다.
resize	—	textarea의 크기 조절 손잡이는 브라우저의 것이고, 내놓을 대응물이 없습니다.
multiline에서의 <textarea>	같은 위젯, 더 높을 뿐	어느 쪽이든 편집기는 하나이므로, 여러 줄로 바꾸는 것이 정말로 높이 말고는 아무것도 바꾸지 않습니다.
aria-describedby 연결	병합된 semantics 노드 하나	경로가 다를 뿐 결과는 같습니다.
터치에서의 선택 손잡이	—	Material과 Cupertino의 것이고, 이 패키지는 둘을 가져오지 않습니다.
className, style, 네이티브 속성	—	전달할 클래스 목록도 style 속성도 없습니다.