src/main/proto/search/now/ui/piet/form_fields.proto

// Copyright 2018 The Feed Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto2";

import "src/main/proto/search/now/ui/piet/elements.proto";

package search.now.ui.piet;

option optimize_for=LITE_RUNTIME;

option java_package = "com.google.search.now.ui.piet";
option java_outer_classname = "FormFieldsProto";
option cc_enable_arenas = true;

// Form Fields can be used to solicit user input and act upon it. Multiple
// visual types of form fields can be used in a Piet layout, all of which are
// represented using the `FormField` proto message.
message FormField {
  // FormFields are implemented in secondary Piet Modules, and thus extend
  // ModuleElement.
  extend ModuleElement {
    optional FormField form_field = 193737014;
  }

  // A unique ID for the Form in which this field appears.
  optional string form_id = 1;

  // A unique ID for this form field. Uniqueness is only required within the
  // same Form. Multiple Forms can have fields with the same ID.
  optional string field_id = 2;

  // All fields are optional by default. If a particular field must be filled
  // in, it should be marked as `is_required`. A required field which has no
  // value provided is considered to have failed validation.
  optional bool is_required = 3 [default = false];

  // The kind of visual presentation to be used for this field.
  oneof form_field_type {
    // A text field that accepts typed text responses.
    TextArea text_area = 4;

    // A list or dropdown that allows selecting one or more options from a list.
    Selectable selectable = 5;

    // A check box or radio button widget.
    Checkable checkable = 6;

    // A numeric range slider that can also handle discrete values.
    Slider slider = 7;
  }
}

// Fillable text field where user can type text or use free-form auto-complete
// suggestions provided by the client platform. A text field can have different
// visual presentations, and `InputType` decides the kinds of inputs that are
// possible. Clients may use the hints provided by `InputType` to provide
// auto-complete for special types (e.g. email, URLs, regular expressions).
message TextArea {
  // Whether this is a special kind of text input; see `InputType`.
  optional InputType input_type = 1;

  // The number of vertical lines to be made visible in the viewport. Content
  // within this field may contain newlines, so
  //   the number of lines in the accepted input text can be more or less than
  //   this number.
  optional int32 lines_visible = 2 [default = 1];

  // Auto-complete suggestion to be shown in the UI.
  optional string value = 3;

  // Text to be shown when the text area’s contents are empty. The hint is
  // usually rendered in a duller font and is immediately hidden as soon as the
  // user types some text.
  optional string hint = 4;

  // If a `regex_pattern` is specified, then the field is considered valid if at
  // least one `regex_pattern` from the set matches user input. Regular
  // expression based validation is only performed when `InputType` is DEFAULT.
  // (i.e., this field is ignored even if provided for types such as PASSWORD,
  // EMAIL, URL, TEL, NUMERIC, DATE, TIME, or COLOR.)
  repeated string regex_pattern = 5;
}

// A dropdown or list-selection widget that shows multiple items, and the user
// can pick one or many from that list.
message Selectable {
  // Whether multiple items from a SELECTABLE field can be selected at once.
  optional bool is_multi_select = 1;

  // The number of vertical lines to be visible in the viewport. Non-positive
  // values are overridden and set to 1. Note that this does not affect how many
  // items can be selected by the user; see `is_multi_select`.
  optional int32 lines_visible = 2 [default = 1];

  // Options to be included in the selectable dropdown or list.
  repeated string options = 3;
}

// A single form field type that represents both, check boxes and radio buttons.
// To group together multiple radio buttons such that only one is selectable at
// a given time, set the same `group_id` on all of them. To use a single
// independent checkbox, ensure that `group_id` is not set.
message Checkable {
  // Multiple checkable fields that have the same `group_id` are treated as
  // mutually exclusive (i.e. like radio buttons) such that checking any one
  // will automatically un-check every other checkable field with the same
  // `group_id`.
  //
  // If no `group_id` is specified, then a checkable field behaves like an
  // independent checkbox. This field may affect the visual presentation of the
  // field (i.e. circular radio button versus square checkbox, depending on
  // platform conventions).
  optional string group_id = 1;
}

// Numeric input types, or non-numeric input types that accept a discrete set
// of values can be represented using sliders. For a read-only progress-bar-like
// appearance, use a slider with `is_enabled` set to false.
message Slider {
  // The minimum value, inclusive.
  optional int32 minimum = 1;

  // The maximum value, inclusive.
  optional int32 maximum = 2;

  // The step between successive values.
  optional int32 step = 3;
}

// For text areas, feature authors can specify in more detail the kinds of input
// they expect to receive. `InputType` can be used for three purposes:
//
// - For Picker UI affordances: clients can show special UIs for special types
//   such as a date picker, time picker, or color picker.
//
// - For Auto-Complete: clients can use `InputType` hints to pre-populate
//   suggestions that may not be available server-side, e.g. email addresses,
//   URLs from history, or frequently-dialed phone numbers.
//
// - For Validation: clients can perform client-side validation of most input
//   types based on the expected text formats (e.g. email, date, time, or via
//   regular expressions).
enum InputType {
  // No special treatment.
  DEFAULT = 0;

  // Any text typed by the user is masked according to platform conventions.
  PASSWORD = 1;

  // Only those characters that are valid in email addresses can be typed into
  // the TEXT field. Client may provide auto-complete suggestions to
  // pre-populate email addresses from client-side data. Typed input must
  // validate as an email address.
  EMAIL = 2;

  // Only those characters that are valid in URLs can be typed into the TEXT
  // field. Client may provide auto-complete suggestions to pre-populate browser
  // navigation URLs from client-side data. Typed input must validate as a URL.
  URL = 3;

  // Only those characters that are valid in (international) telephone numbers
  // can be typed into the TEXT field. Client may provide auto-complete
  // suggestions to pre-populate browser navigation URLs from client-side data.
  // Typed input must validate as a phone number.
  TEL = 4;

  // Only numeric characters can be typed into the TEXT field. If a range is
  // provided, then typed input must be within the acceptable range. NUMERIC can
  // be used with either TEXT or SLIDER visual types.
  NUMERIC = 5;

  // Clients may provide a Date Picker widget TEXT fields of type DATE.
  DATE = 6;

  // Clients may provide a Time Picker widget TEXT fields of type TIME.
  TIME = 7;

  // Clients may provide a Color Picker widget TEXT fields of type COLOR. The
  // returned value is a color in ARGB hex form with a preceding literal '#'
  // (#AARRGGBB).
  COLOR = 8;
}