Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
22.8 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.
// Adapted from github.com/ejc3/astryx-swift (MIT).

/// A labeled one-line text field, painted with the theme's tokens. It takes
/// core's TextInput props (`TextInputProps`): the label stays visible above
/// the field unless hidden, and is the field's accessible name either way.
public struct TextInput: View {
  public let props: TextInputProps
  @Environment(\.astryx) private var astryx
  /// Which of the field's two parts holds focus: the editable field, or the
  /// drawn read-only or disabled field.
  enum FieldFocus: Hashable { case editable, drawn }
  @FocusState private var focus: FieldFocus?
  /// Set on the first appearance, so a field that scrolls back into view in a
  /// List or Form does not announce or take focus again.
  @State private var hasAppeared = false

  public init(_ props: TextInputProps) {
    self.props = props
  }

  /// - Parameters:
  ///   - label: core's `label`, the field's visible and accessible name.
  ///   - value: core's `value`, the text the field shows.
  ///   - type: core's `type`: `text`, `email`, or `password`.
  ///   - onChange: core's `onChange`, called with each edit.
  ///   - size: core's `size`; `md` when nil.
  ///   - isLabelHidden: core's `isLabelHidden`: no visible label, the same
  ///     accessible name.
  ///   - description: core's `description`, shown between the label and the
  ///     field and read after the label.
  ///   - isOptional: core's `isOptional`, an "Optional" note after the label.
  ///   - isRequired: core's `isRequired`, a "Required" note after the label.
  ///   - onEnter: core's `onEnter`, called when the person submits the field
  ///     (Return), never while an input method is still composing.
  ///   - isDisabled: core's `isDisabled`: dimmed and not editable.
  ///   - isReadOnly: core's `isReadOnly`: shown at full strength, selectable,
  ///     not editable.
  ///   - disabledMessage: core's `disabledMessage`, why a disabled field is
  ///     disabled: a tip on hover or tap, and read after the label.
  ///   - isLoading: core's `isLoading`: a spinner, and "Loading" spoken once
  ///     when it starts.
  ///   - placeholder: core's `placeholder`.
  ///   - labelTooltip: core's `labelTooltip`, a tip on an info icon after the
  ///     label: on hover or tap.
  ///   - status: core's `status`: a colored border and status icon, and its
  ///     message below the field.
  ///   - statusVariant: core's `statusVariant`: the message `attached` to the
  ///     field (default), `detached` below it, or in a `tooltip` on the icon.
  ///   - hasClear: core's `hasClear`, a clear button while there is text.
  ///   - hasAutoFocus: core's `hasAutoFocus`, focus when the field appears.
  ///   - base: core's base props; `id` names the field itself.
  public init(
    label: String,
    value: String,
    type: TextInputType? = nil,
    onChange: ((String) -> Void)? = nil,
    size: TextInputSize? = nil,
    isLabelHidden: Bool? = nil,
    description: String? = nil,
    isOptional: Bool? = nil,
    isRequired: Bool? = nil,
    onEnter: (() -> Void)? = nil,
    isDisabled: Bool? = nil,
    isReadOnly: Bool? = nil,
    disabledMessage: String? = nil,
    isLoading: Bool? = nil,
    placeholder: String? = nil,
    labelTooltip: String? = nil,
    status: TextInputStatus? = nil,
    statusVariant: TextInputStatusVariant? = nil,
    hasClear: Bool? = nil,
    hasAutoFocus: Bool? = nil,
    base: AstryxBaseProps = AstryxBaseProps()
  ) {
    self.init(
      TextInputProps(
        type: type,
        label: label,
        value: value,
        onChange: onChange,
        size: size,
        isLabelHidden: isLabelHidden,
        description: description,
        isOptional: isOptional,
        isRequired: isRequired,
        onEnter: onEnter,
        isDisabled: isDisabled,
        isReadOnly: isReadOnly,
        disabledMessage: disabledMessage,
        isLoading: isLoading,
        placeholder: placeholder,
        labelTooltip: labelTooltip,
        status: status,
        statusVariant: statusVariant,
        hasClear: hasClear,
        hasAutoFocus: hasAutoFocus,
        base: base
      )
    )
  }

  var isDisabled: Bool { props.isDisabled == true }
  /// Disabled wins when both are set, as in core.
  var isReadOnly: Bool { props.isReadOnly == true && !isDisabled }
  var statusVariant: TextInputStatusVariant { props.statusVariant ?? .attached }

  public var body: some View {
    SwiftUI.VStack(alignment: .leading, spacing: astryx.tokens.space.s1) {
      if props.isLabelHidden != true {
        labelRow
      }
      // A hidden label hides the description with it, as core's field does;
      // VoiceOver still reads it on the field. A shown description is also
      // its own text in the reading order, as core's is.
      if props.isLabelHidden != true, let description = props.description {
        Text(description, type: .supporting, color: .secondary)
      }
      SwiftUI.VStack(alignment: .leading, spacing: 0) {
        // Base `isHidden` targets the control, as `id` does: the control and
        // its buttons leave layout and focus, while the label, description,
        // and status stay (AST-082 FR7).
        if !hidesControl {
          fieldRow
        }
        statusMessage
      }
    }
    .onAppear {
      guard !hasAppeared else { return }
      hasAppeared = true
      if props.hasAutoFocus == true, !hidesControl { focus = isDrawn ? .drawn : .editable }
      // A field that appears busy says so, as core announces a busy start.
      if props.isLoading == true { AccessibilityNotification.Announcement(AstryxStrings.spinnerLoading).post() }
      // A status message already present when the field appears is
      // announced too, as core's field status does.
      if let announcement = statusAnnouncement { announce(announcement) }
    }
    .onChange(of: props.isLoading == true) { _, loading in
      if loading { AccessibilityNotification.Announcement(AstryxStrings.spinnerLoading).post() }
    }
    .onChange(of: statusAnnouncement) { _, announcement in
      // A status message that appears or changes is announced: an error at
      // once, others when VoiceOver is free, as core's field status does.
      if let announcement { announce(announcement) }
    }
  }

  // MARK: Label

  /// The note after the label: "Optional" or "Required".
  /// `isOptional` wins when both are set, as in core.
  var labelNote: String? {
    if props.isOptional == true { return AstryxStrings.fieldOptional }
    if props.isRequired == true { return AstryxStrings.fieldRequired }
    return nil
  }

  /// The status message to announce when the field appears with it, and when
  /// its words or its type change.
  struct StatusAnnouncement: Equatable {
    var message: String
    var type: TextInputStatusType
    var isError: Bool { type == .error }
  }

  var statusAnnouncement: StatusAnnouncement? {
    guard let status = props.status, let message = status.message else { return nil }
    return StatusAnnouncement(message: message, type: status.type)
  }

  /// Posts a status message: an error at once, others when VoiceOver is free.
  func announce(_ announcement: StatusAnnouncement) {
    var words = AttributedString(announcement.message)
    words.accessibilitySpeechAnnouncementPriority = announcement.isError ? .high : .default
    AccessibilityNotification.Announcement(words).post()
  }

  private var labelRow: some View {
    SwiftUI.HStack(alignment: .firstTextBaseline, spacing: astryx.tokens.space.s1) {
      // The field reads the label and its note, so VoiceOver skips them here
      // while the field shows; with the field hidden they are read as text.
      Text(props.label, type: .label, color: isDisabled ? .disabled : .secondary, weight: .medium)
        .accessibilityHidden(!hidesControl)
      if let note = labelNote {
        Text("∙ \(note)", type: .supporting, color: .secondary, weight: .normal)
          .accessibilityHidden(!hidesControl)
      }
      if let tip = props.labelTooltip {
        tipIcon(tip, icon: "info", label: tip)
          .foregroundStyle(astryx.tokens.color.textSecondary)
      }
    }
  }

  // MARK: Field

  /// The field's accessible name: the label and its note, as core's label
  /// element names the input.
  var accessibilityName: String {
    labelNote.map { "\(props.label), \($0)" } ?? props.label
  }

  /// The label VoiceOver reads on the field: the name, then an error, since
  /// SwiftUI has no invalid state and a hint is skipped with Speak Hints off.
  var accessibilityLabelText: String {
    guard let status = props.status, status.type == .error else { return accessibilityName }
    return "\(accessibilityName), \(status.message ?? AstryxStrings.statusButton(.error))"
  }

  /// What VoiceOver reads after the name: the description, the status message,
  /// and the disabled reason, in core's `aria-describedby` order.
  /// An error leads, since SwiftUI has no invalid state to expose: its
  /// message, or the error status name when it has none. A read-only field
  /// says so, as core does where a control cannot expose read-only.
  var accessibilityDescription: String {
    var parts: [String] = []
    if let description = props.description { parts.append(description) }
    if let status = props.status, status.type != .error, let message = status.message { parts.append(message) }
    if isReadOnly { parts.append(AstryxStrings.inputReadOnly) }
    if isDisabled, let reason = props.disabledMessage { parts.append(reason) }
    return parts.joined(separator: ", ")
  }

  /// Edits reach `onChange` only while the field can be edited.
  var text: Binding<String> {
    Binding(
      get: { props.value },
      set: { newValue in
        guard !isDisabled, !isReadOnly else { return }
        props.onChange?(newValue)
      }
    )
  }

  private var fieldRow: some View {
    let shape = RoundedRectangle(cornerRadius: astryx.tokens.radius.element, style: .continuous)
    return SwiftUI.HStack(spacing: astryx.tokens.space.s2) {
      field
        .font(astryx.font(TypeStyle(astryx.tokens.font.body, families: astryx.tokens.font.family.body)))
        .foregroundStyle(astryx.tokens.color.textPrimary)
        .onSubmit { props.onEnter?() }
        .accessibilityLabel(SwiftUI.Text(accessibilityLabelText))
        .accessibilityHint(SwiftUI.Text(accessibilityDescription))
        .astryxIdentifier(props.base.id)
      if props.isLoading == true {
        ProgressView().controlSize(.small).accessibilityHidden(true)
      }
      // Trailing controls sit side by side, each across its own 44-point
      // target, so no two tap regions overlap.
      SwiftUI.HStack(spacing: 0) {
        if showsClear {
          SwiftUI.Button {
            props.onChange?("")
            focus = .editable
          } label: {
            icon("close").frame(minWidth: 44, minHeight: 44).contentShape(Rectangle())
          }
          .buttonStyle(.plain)
          .foregroundStyle(astryx.tokens.color.textSecondary)
          .astryxTooltip(AstryxStrings.clearTooltip, focus: .control)
          .accessibilityLabel(SwiftUI.Text(AstryxStrings.clearLabel(props.label)))
        }
        statusIcon
          .frame(minWidth: hasTrailingButtons ? 44 : nil)
      }
    }
    .padding(.leading, astryx.tokens.space.s3)
    .padding(.trailing, hasTrailingButtons ? 0 : astryx.tokens.space.s3)
    .frame(minHeight: max(44, height * astryx.textScale))
    .background(
      shape.strokeBorder(borderColor, lineWidth: astryx.tokens.size.borderWidth)
    )
    .opacity(isDisabled ? 0.5 : 1)
    // A disabled field shows its reason in the shared tooltip on hover, on
    // keyboard focus of its drawn field, and on a tap; VoiceOver reads the
    // reason on the field.
    .astryxTooltip(isDisabled ? props.disabledMessage : nil, focus: reasonTooltipFocus, touch: .tap)
  }

  /// How keyboard focus opens the disabled reason: the row holds the drawn
  /// field, which takes the focus, so focus inside the row opens it, as
  /// Thumbnail's tooltip does for its parts.
  var reasonTooltipFocus: TooltipFocus { .inside(focus == .drawn) }

  /// Whether the field row ends in buttons, whose 44-point targets reach its
  /// edge in place of the trailing padding.
  var hasTrailingButtons: Bool {
    showsClear || (statusVariant == .tooltip && props.status?.message != nil)
  }

  /// A disabled field keeps its focus stop, as core's disabled input does
  /// (`aria-disabled`), so keyboard users reach it and its reason.
  var keepsFocusWhileDisabled: Bool { isDisabled }

  /// Base `isHidden` hides the field control, TextInput's base target.
  var hidesControl: Bool { props.base.isHidden == true }

  var showsClear: Bool {
    props.hasClear == true && !props.value.isEmpty && !isDisabled && !isReadOnly
  }

  var height: CGFloat {
    switch props.size ?? .md {
    case .sm: astryx.tokens.size.elementSm
    case .md: astryx.tokens.size.elementMd
    case .lg: astryx.tokens.size.elementLg
    }
  }

  var borderColor: Color {
    let color = astryx.tokens.color
    guard !isDisabled, let status = props.status else { return color.borderEmphasized }
    // The status border role, at 3:1 or more on the page (theme tokens INV11).
    switch status.type {
    case .error: return color.borderError
    case .warning: return color.borderWarning
    case .success: return color.borderSuccess
    }
  }

  /// Whether the field draws its value instead of the editable field.
  var isDrawn: Bool { isReadOnly || keepsFocusWhileDisabled }

  /// Both parts stay in one view structure, so a field that becomes read-only
  /// or disabled keeps its identity and its focus moves to the drawn part, as
  /// core keeps focus on an input that becomes disabled (`spec:AST-085`).
  private var field: some View {
    ZStack(alignment: .leading) {
      editableField
        .focused($focus, equals: .editable)
        .disabled(isDrawn)
        .opacity(isDrawn ? 0 : 1)
        .accessibilityHidden(isDrawn)
      readOnlyField
        .focusable(isDrawn)
        .focused($focus, equals: .drawn)
        .opacity(isDrawn ? 1 : 0)
        .allowsHitTesting(isDrawn)
        .accessibilityHidden(!isDrawn)
    }
    .onChange(of: isDrawn) { _, drawn in
      if focus != nil { focus = drawn ? .drawn : .editable }
    }
  }

  @ViewBuilder private var editableField: some View {
    let prompt = props.placeholder.map {
      SwiftUI.Text($0).foregroundStyle(astryx.tokens.color.textSecondary)
    }
    switch props.type ?? .text {
    case .password:
      SecureField("", text: text, prompt: prompt)
        .textContentType(.password)
    case .email:
      TextField("", text: text, prompt: prompt)
        .textContentType(.emailAddress)
        .autocorrectionDisabled()
        #if os(iOS)
        .keyboardType(.emailAddress)
        .textInputAutocapitalization(.never)
        #endif
    case .text:
      TextField("", text: text, prompt: prompt)
    }
  }

  /// What a read-only field shows: the value, masked for a password.
  var readOnlyText: String {
    props.type == .password ? String(repeating: "\u{2022}", count: props.value.count) : props.value
  }

  /// Whether a read-only field shows its placeholder: when it has no value.
  var showsReadOnlyPlaceholder: Bool { props.value.isEmpty && props.placeholder != nil }

  /// Read-only or disabled: the value, never editable, with the placeholder
  /// when empty. It keeps a focus stop, as core's read-only and disabled
  /// inputs do, without raising a keyboard; Return runs `onEnter` only while
  /// read-only. VoiceOver reads a SwiftUI text field in its place, dimmed when
  /// disabled, with "Read only" or the disabled reason in its description,
  /// since a SwiftUI text field cannot be read-only and a disabled one takes
  /// no focus. A password stays masked and cannot be selected or copied.
  @ViewBuilder private var readOnlyField: some View {
    let shown = showsReadOnlyPlaceholder
      ? SwiftUI.Text(props.placeholder ?? "").foregroundStyle(astryx.tokens.color.textSecondary)
      : SwiftUI.Text(readOnlyText)
    // One line, as the field it stands in for: it stays laid out under the
    // editable field, so a long value must not make that field grow taller.
    let text = shown
      .lineLimit(1)
      .frame(maxWidth: .infinity, alignment: .leading)
      .onKeyPress(.return) {
        guard isReadOnly else { return .ignored }
        props.onEnter?()
        return .handled
      }
      // VoiceOver reads it as the platform's text field: dimmed when
      // disabled, a secure field for a password, with the name and the
      // description the field reads in every state.
      .accessibilityRepresentation { accessibleField }
    if props.type == .password {
      text.textSelection(.disabled)
    } else {
      text.textSelection(.enabled)
    }
  }

  /// What VoiceOver reads for a read-only or disabled field: which platform
  /// field, whether it is dimmed, and its label, value, and description.
  struct AccessibleField: Equatable {
    enum Kind: Equatable { case text, secure }
    var kind: Kind
    var isDimmed: Bool
    var label: String
    var value: String
    var hint: String
  }

  var accessibleFieldDescription: AccessibleField {
    AccessibleField(
      kind: props.type == .password ? .secure : .text,
      isDimmed: isDisabled,
      label: accessibilityLabelText,
      value: props.value,
      hint: accessibilityDescription
    )
  }

  /// The platform text field VoiceOver reads for a read-only or disabled field.
  @ViewBuilder private var accessibleField: some View {
    let field = accessibleFieldDescription
    let value = Binding.constant(field.value)
    Group {
      switch field.kind {
      case .secure: SecureField(field.label, text: value)
      case .text: TextField(field.label, text: value)
      }
    }
    .disabled(field.isDimmed)
    .accessibilityHint(SwiftUI.Text(field.hint))
  }

  // MARK: Status

  /// The status icon in the field: plain when attached, a tip button when the
  /// message shows in a tip, and none when detached (its message has one).
  @ViewBuilder private var statusIcon: some View {
    if let status = props.status, statusVariant != .detached {
      if statusVariant == .tooltip, let message = status.message {
        tipIcon(message, icon: status.type.rawValue, label: AstryxStrings.statusButton(status.type), inField: true, isButton: true)
          .foregroundStyle(statusColor(status.type))
      } else {
        icon(status.type.rawValue)
          .foregroundStyle(statusColor(status.type))
          .accessibilityHidden(true)
      }
    }
  }

  /// The message box below the field, attached to it or detached from it.
  @ViewBuilder private var statusMessage: some View {
    if let status = props.status, let message = status.message, statusVariant != .tooltip {
      let detached = statusVariant == .detached
      let radius = astryx.tokens.radius.element
      SwiftUI.HStack(alignment: .firstTextBaseline, spacing: astryx.tokens.space.s1) {
        if detached {
          icon(status.type.rawValue).accessibilityHidden(true)
        }
        SwiftUI.Text(message)
          .font(astryx.font(TypeStyle(astryx.tokens.font.supporting, families: astryx.tokens.font.family.body)))
      }
      .foregroundStyle(messageColor(status.type))
      .frame(maxWidth: .infinity, alignment: .leading)
      .padding(.horizontal, astryx.tokens.space.s2)
      .padding(.vertical, astryx.tokens.space.s2)
      .background(
        UnevenRoundedRectangle(
          topLeadingRadius: detached ? radius : 0,
          bottomLeadingRadius: radius,
          bottomTrailingRadius: radius,
          topTrailingRadius: detached ? radius : 0,
          style: .continuous
        )
        .fill(messageGround(status.type))
      )
      .padding(.top, detached ? astryx.tokens.space.s1 : 0)
      // The message is also its own text in the reading order, as core's is.
      .accessibilityElement(children: .combine)
    }
  }

  /// The status icon role on the page (theme tokens INV11).
  func statusColor(_ type: TextInputStatusType) -> Color {
    let color = astryx.tokens.color
    switch type {
    case .error: return color.iconError
    case .warning: return color.iconWarning
    case .success: return color.iconSuccess
    }
  }

  /// Content on the muted status ground, at 4.5:1 or more (theme tokens INV11).
  func messageColor(_ type: TextInputStatusType) -> Color {
    let color = astryx.tokens.color
    switch type {
    case .error: return color.onErrorMuted
    case .warning: return color.onWarningMuted
    case .success: return color.onSuccessMuted
    }
  }

  func messageGround(_ type: TextInputStatusType) -> Color {
    let color = astryx.tokens.color
    switch type {
    case .error: return color.errorMuted
    case .warning: return color.warningMuted
    case .success: return color.successMuted
    }
  }

  // MARK: Tips

  /// An icon that shows `text` in the shared Astryx tooltip: on hover with a
  /// pointer, on keyboard focus (it is a tab stop), and on a direct tap, as
  /// core's tooltip icon does. VoiceOver reads it as `label` with `text` as
  /// the hint. In the field row it lays out across its whole 44-point target;
  /// beside the label it reaches 44 points without growing the row.
  /// A status tip is a button, as core's status icon is a `<button>`:
  /// activating it with VoiceOver speaks its message.
  private func tipIcon(_ text: String, icon name: String, label: String, inField: Bool = false, isButton: Bool = false) -> some View {
    let tip = TipAccessibility(text: text, label: label, isButton: isButton)
    return icon(name)
      .frame(minWidth: inField ? 44 : nil, minHeight: inField ? 44 : nil)
      .contentShape(Rectangle())
      .astryxMinimumHitArea(inField ? 44 : iconSide)
      .accessibilityElement()
      .accessibilityLabel(SwiftUI.Text(tip.label))
      .accessibilityAddTraits(tip.isButton ? .isButton : [])
      .accessibilityAction {
        if tip.isButton { AccessibilityNotification.Announcement(tip.text).post() }
      }
      .astryxTooltip(text, hint: tip.hint, focus: .tabStop, touch: .tap)
  }

  /// What VoiceOver gets for a tip icon: its name, whether it is a button, and
  /// its words as the hint unless they are the name.
  struct TipAccessibility: Equatable {
    var text: String
    var label: String
    var isButton: Bool
    var hint: String? { label == text ? nil : text }
  }

  /// The tooltip-variant status tip's accessibility, for the current status.
  var statusTipAccessibility: TipAccessibility? {
    guard statusVariant == .tooltip, let status = props.status, let message = status.message else { return nil }
    return TipAccessibility(text: message, label: AstryxStrings.statusButton(status.type), isButton: true)
  }

  /// A shared icon at the supporting text size: the theme's SF Symbol or app
  /// asset, else the default symbol; a name nothing maps draws nothing.
  var iconSide: CGFloat { astryx.tokens.font.supporting.size * astryx.textScale }

  @ViewBuilder private func icon(_ name: String) -> some View {
    let side = iconSide
    if let image = astryx.icon(name) {
      image.sized(side).font(.system(size: side))
    }
  }
}