GPUI Deck

Field

Input/Textarea 기반 컨트롤의 레이블 포커스, 도움말/오류 설명, required/invalid 메타데이터, 그리고 Checkbox, Switch, RadioGroup, Select를 위한 ControlField.

GPUI 웹 백엔드가 그리는 실제 컴포넌트입니다. WebGPU를 지원하는 브라우저가 필요합니다.

Field::new(id, &input_state, label)은 보이는 레이블, 선택적 도움말, 검증 피드백을 유지되는 입력 하나와 연결합니다. 같은 생성자가 InputState와 TextareaState를 받으며, Combobox는 input()으로 질의 입력을 노출합니다. 그 입력의 렌더러는 Field의 자식으로 둡니다. 레이블은 클릭할 수 있고, 살아 있는 활성 입력에 포커스를 주며, Tab 스톱을 추가하지 않습니다.

Field::new("session-name-field", &self.input, "Session name")
    .description("Choose a name to recognize this session.")
    .required(true)
    .error(name_invalid.then(|| "A session name is required.".into()))
    .styles(|styles| {
        styles
            .description(|style| style.text_color(muted))
            .error(|style| style.text_color(error_color))
    })
    .flex()
    .flex_col()
    .gap_1()
    .child(input_frame)

검증과 제출은 애플리케이션이 소유합니다. 네이티브 예제에서는 이름이 비어 있으면 오류가 표시되고 Done이 비활성화되며, 이름을 입력하면 둘 다 해제됩니다. Field는 레이블, 컨트롤 자식, 도움말, 오류를 순서대로 렌더링하고, 스타일은 FieldStyles로 제공받습니다. 색상 팔레트, 검증 스키마, 폼 컨트롤러는 제공하지 않습니다. 컨트롤 연결은 유지되는 텍스트 입력 계열을 다루며, 선택형 컨트롤은 아래의 ControlField가 다룹니다.

실제 네이티브 입력은 레이블, 오류가 도움말보다 앞선 설명, required/invalid 플래그를 받습니다. 기존 역할, 플레이스홀더, 접근성 식별자, 값 노출 정책, 팝업 펼침 상태는 보존됩니다. error(None)을 전달하면 invalid 상태가 해제됩니다. 이를 뒷받침하는 InputAccessibility 빌더는 with_description, with_required, with_invalid이며, 편집과 포커스의 소유자는 여전히 입력뿐입니다.

선택형 컨트롤을 위한 ControlField

ControlField::new(id, &focus, label)은 Checkbox, Switch, RadioGroup, Select에 같은 레이블, 도움말, 오류, required/invalid 계약을 제공합니다. .control(|metadata| ...) 빌더는 FieldMetadata를 받습니다. 이를 컨트롤의 .field(metadata)에 전달하면 컨트롤에 이름을 붙이고, 오류를 도움말보다 앞세워 설명하며, 기존 네이티브 노드를 required 또는 invalid로 표시합니다. 필드 레이블이 컨트롤 자체의 accessibility_label보다 우선합니다.

ControlField::new("stroke-width-field", &checked_option_focus, "Stroke width")
    .description("Applies to new strokes.")
    .control(move |metadata| stroke_group.field(metadata))

레이블을 클릭하면 Tab 스톱을 추가하지 않고 focus에 포커스를 줍니다. Checkbox나 Switch에서는 HTML label처럼 .on_label_activate(...)가 이어서 애플리케이션 값을 토글하며, .control_first(true)는 컨트롤을 레이블보다 먼저 그립니다. .disabled(true)는 비활성화된 컨트롤을 반영해 레이블이 포커스를 주거나 활성화하지 않게 합니다. RadioGroup에는 체크된 옵션의 포커스 핸들을 전달합니다. Settings Preferences 뷰는 이 방식으로 Stroke width를 감쌉니다. 레이아웃과 검증은 애플리케이션이 소유합니다.