src/main/proto/search/now/ui/piet/piet.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";

package search.now.ui.piet;

option optimize_for=LITE_RUNTIME;

import "src/main/proto/search/now/ui/piet/actions.proto";
import "src/main/proto/search/now/ui/piet/elements.proto";
import "src/main/proto/search/now/ui/piet/log_data.proto";
import "src/main/proto/search/now/ui/piet/media_queries.proto";
import "src/main/proto/search/now/ui/piet/styles.proto";

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

// Piet • [INTERNAL LINK] • [INTERNAL LINK]
//
// Piet is a declarative UI rendering spec with a set of cross-platform
// libraries that can render the same exact proto on Android, iOS and Web to
// generate similar visual layouts.

// DOCS
//
// Before using Piet, make sure to read the following docs:
// - Core Design: [INTERNAL LINK]
// - Client Support: [INTERNAL LINK]
// - Error Handling: [INTERNAL LINK]
//
// IDs
//
// Every field that ends in `_id` must be unique within its containing message.
// Examples:
// - Style.style_id must be unique within a Stylesheet.
// - Stylesheet.stylesheet_id must be unique within PietSharedState.
// - Template.template_id must be unique within PietSharedState.
// - BindingRef.binding_id must be unique within its containing Template.
// etc.
//
// TAG
//
// Fields named `tag` are open-ended and never used for any processing. Servers,
// Clients, and Hosts may use these fields as they see fit, mostly for debugging
// purposes.
//
// COLORS
//
// - Although colors are expressed as 32-bit ARGB (Alpha, Red, Green, Blue)
//   channels, not all platforms may support alpha.
// - Colors have no meaningful default and must be specified explicitly wherever
//   needed.
// - If a platform requires an alternate representation for convenience, (e.g.
//   CSS-style #000000 format), such representations should be segregated in
//   platform-specific support protos, e.g. `piet_web_support.proto`.
//
// DIMENSIONS
//
// - All measurements are in dp (display pixels) unless otherwise specified.
// - Negative values are officially unsupported, though they may happen to work
//   in certain circumstances. Unless explicitly documented otherwise, do not
//   assume that they will continue to work the same way across multiple client
//   implementations or versions.
//
// -----------------------------------------------------------------------------

// A Frame is the top-level UI construct in Piet. Every layout is contained
// within a Frame. Each frame defines the contents displayed to the user as a
// single view, which may contain a complex set of child views.
// NextId: 13
message Frame {
  // A string tag for the frame, currently used for debugging purposes. Need not
  // be unique.
  optional string tag = 1;

  // UI Elements in a Frame use a Stylesheet to resolve the Styles that define
  // their appearance. This Stylesheet can either be provided directly inlined
  // in every Frame, or via a lookup in the global shared state in
  // PietSharedState.
  //
  // NOTE: Styles from this Stylesheet are not available to Templates; they can
  // only be used by Elements defined directly in this Frame itself, such as
  // non-template Content, or ElementLists bound to Templates. This limitation
  // is a performance optimization that makes view recycling efficient. This
  // applies to both the inlined Stylesheet and stylesheet_id's referencing a
  // PietSharedState Stylesheet.
  //
  // DEPRECATED: Use stylesheets field instead. If that field is set, these
  // deprecated fields will be ignored.
  oneof frame_style_scope {
    // If this is defined, the Stylesheet for the Frame is found by a lookup
    // in PietSharedState.Stylesheets. If the stylesheet_id cannot be found,
    // ERR_MISSING_STYLESHEET is raised.
    // DEPRECATED: use stylesheets field instead.
    string stylesheet_id = 2 [deprecated = true];

    // A local Stylesheet that provides styles used by Elements in this Frame.
    // DEPRECATED: use stylesheets field instead.
    Stylesheet stylesheet = 3 [deprecated = true];
  }

  // Defines the Stylesheets used by this Frame.
  //
  // NOTE: Styles from this Stylesheet are not available to Templates; they can
  // only be used by Elements defined directly in this Frame itself, such as
  // non-template Content. This limitation is a performance optimization that
  // makes view recycling efficient. This applies to both the inlined
  // Stylesheets and stylesheet_id's referencing a PietSharedState Stylesheet.
  optional Stylesheets stylesheets = 11;

  // Styles applied to this Frame. If any style_ids cannot be found,
  // ERR_MISSING_STYLES is raised.
  optional StyleIdsStack style_references = 4;

  // Templates that are available for use within the scope of this Frame.
  repeated Template templates = 5;

  // Content that makes up this Frame.
  //
  // There are a few differences in the use of Content here vs. elsewhere:
  //  - These Contents are arranged in a vertical list layout.
  //  - Bindings are not supported in these Contents, since there is no
  //    BindingContext available at the Frame level.
  //  - These Contents support sharding: each of these Contents can be recycled
  //    as it leaves the screen, to reduce memory usage when scrolling a very
  //    long Frame.
  repeated Content contents = 10;

  // Actions associated with the full Frame.
  optional Actions actions = 7;

  // Data used for logging info sent to the host.
  optional LogData log_data = 12;

  // Please use CL numbers you own for extension numbers.
  extensions 10000 to max;

  // Deprecated field IDs.
  reserved 6, 9, 8;
}

// UI Elements in a Frame or Template use a Stylesheet to resolve the Styles
// that define their appearance. The Stylesheet is constructed by combining
// Styles from any Stylesheets referenced here; Stylesheets can by directly
// inlined, or referenced from the global shared state in PietSharedState.
// Piet will report ERR_DUPLICATE_STYLE if multiple Styles across any of the
// Stylesheets have the same style id (after MediaQueryCondition filtering).
message Stylesheets {
  // Stylesheets to be fetched from the global PietSharedState.
  // If a stylesheet_id cannot be found, ERR_MISSING_STYLESHEET is raised.
  repeated string stylesheet_ids = 1;

  // Inline Stylesheets. These can be filtered by MediaQueryCondition.
  repeated Stylesheet stylesheets = 2;
}

// A set of Styles; each Style must have a style_id that is unique within this
// Stylesheet. If the same style_id is found twice, ERR_DUPLICATE_STYLES is
// raised. Stylesheet is scoped to Frames or Templates. When a UI element uses a
// Style, it is looked up in the Stylesheet within scope. If the style cannot be
// found, ERR_MISSING_STYLES is raised.
message Stylesheet {
  // A string uniquely identifying this Stylesheet within the PietSharedState in
  // which it is used. If two Stylesheets with the same stylesheet_id are found
  // in a PietSharedState, ERR_DUPLICATE_STYLESHEET is raised. This
  // `stylesheet_id` is used to select this Stylesheet using
  // Frame.stylesheet_id.
  optional string stylesheet_id = 1;

  // Styles available in this Stylesheet.
  repeated Style styles = 2;

  // This Stylesheet is only eligible to be used if *all* the conditions
  // enumerated below are met. If even one condition is unsatisfied,
  // this Stylesheet is treated as if it was never sent, which may cause
  // ERR_STYLESHEET_NOT_FOUND.
  repeated MediaQueryCondition conditions = 3;
}

// A Template defines a reusable ElementList. The content is data-bound from
// Bindings in the TemplateInvocation. Templates allow consistent creation of
// elements using bound data. For example, table rows with different values, or
// GridCells with different data values.
message Template {
  // A unique identifier for this template. If two Templates with the same
  // template_id are found in a PietSharedState, ERR_DUPLICATE_TEMPLATE is
  // raised.
  optional string template_id = 1;

  // The Stylesheet used within this Template's scope.
  // - Styles from the Frame CANNOT be referenced from within a Template.
  // - Styles from the PietSharedState CAN be referenced, only if the
  //   stylesheet_id is defined by the Template.
  //
  // DEPRECATED: Use stylesheets field instead. If that field is set, these
  // deprecated fields will be ignored.
  oneof template_stylesheet {
    // If defined, the Stylesheet for this Template is looked up in
    // PietSharedState.Stylesheets. If the stylesheet_id cannot be found,
    // ERR_MISSING_STYLESHEET is raised.
    // DEPRECATED: use stylesheets field instead.
    string stylesheet_id = 2 [deprecated = true];

    // A local Stylesheet. Styles in this Stylesheet will only be available to
    // elements defined in this Template.
    // DEPRECATED: use stylesheets field instead.
    Stylesheet stylesheet = 3 [deprecated = true];
  }

  // The Stylesheets used within this Template's scope.
  // - Styles from the Frame CANNOT be referenced from within a Template.
  // - Styles from the PietSharedState CAN be referenced, only if the
  //   stylesheet_id is defined by the Template.
  optional Stylesheets stylesheets = 11;

  // Styles applied to all child views of this Template.
  optional StyleIdsStack child_default_style_ids = 4 [deprecated = true];

  // Content defined by this Template.
  optional Element element = 6;

  // This Template is only eligible to be used if *all* the conditions
  // enumerated below are met. If even one condition is unsatisfied, this
  // Template is treated as if it was never sent, which may cause
  // ERR_TEMPLATE_NOT_FOUND.
  repeated MediaQueryCondition conditions = 8;

  // Please use CL numbers you own for extension numbers.
  extensions 10000 to max;

  // Deprecated field IDs.
  reserved 5;
}

// State shared among multiple Frame instances. This is a top-level object,
// defined outside individual Frame instances.
message PietSharedState {
  // Stylesheet definitions that can be reused across Frames.
  // Stylesheet.stylesheet_id must be unique within the List, otherwise
  // ERR_DUPLICATE_STYLESHEET is raised.
  repeated Stylesheet stylesheets = 1;

  // Template definitions that can be reused across Frames. Each Template may
  // define their own Stylesheet, or can access a Stylesheet defined in this
  // PietSharedState. If two or more Templates with the same template_id are
  // found, then ERR_DUPLICATE_TEMPLATE is raised.
  repeated Template templates = 2;
}