// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.accessibility.semantics;

using fuchsia.ui.gfx;

/// Max number of elements in a semantic set.
const MAX_SET_ELEMENTS uint32 = 100;

/// Represents actions that can be applied to Nodes.
type Action = strict enum {
    /// The default action associated with the element.
    DEFAULT = 1;
    /// The secondary action associated with the element. This may correspond to a long press
    /// (touchscreens) or right click (mouse).
    SECONDARY = 2;
    /// Set (input/non-accessibility) focus on this element.
    SET_FOCUS = 3;
    /// Set the element's value.
    SET_VALUE = 4;
    /// Scroll node to make it visible.
    SHOW_ON_SCREEN = 5;
    /// Decrement a slider by one step value. The step size is defined by the
    /// owner of the semantic node that executes this action. For example, a
    /// volume slider may want to make steps 1, 2, 3, while a time slider may
    /// want to skip 30 seconds each step change.
    DECREMENT = 6;
    /// Increment a slider by one step value. The step size is defined by the
    /// owner of the semantic node that executes this action. For example, a
    /// volume slider may want to make steps 1, 2, 3, while a time slider may
    /// want to skip 30 seconds each step change.
    INCREMENT = 7;
};

/// Represents a role of an element on a UI.
type Role = strict enum {
    /// Role used to represent elements which role is not currently supported.
    UNKNOWN = 1;
    /// Something on screen that can be clicked/activated, that has a single function.
    BUTTON = 2;
    /// Header text, e.g. something tagged <h1> in HTML.
    HEADER = 3;
    /// An image or graphic.
    IMAGE = 4;
    /// A field that can receive text input.
    TEXT_FIELD = 5;
    /// A slider, e.g. a volume slider or a time slider of a video.
    SLIDER = 6;
    /// A link, e.g. a link on a webpage.
    LINK = 7;
    /// A check box that can be toggled.
    CHECK_BOX = 8;
    /// A radio button that selects an option among a group of options.
    RADIO_BUTTON = 9;

    /// Role used to represent lists.
    LIST = 10;

    /// Role used to represent an element in a list, including its marker and
    /// its content. For example, a element tagged <li>, or an element with the
    /// ARIA listitem role.
    LIST_ELEMENT = 11;

    /// Role used to represent a list marker (e.g. a bullet point, number, roman
    /// numeral, etc.).
    LIST_ELEMENT_MARKER = 12;

    /// Role used to represent immutable text.
    STATIC_TEXT = 13;

    /// Role used to represent toggle switch.
    TOGGLE_SWITCH = 14;

    /// Role used to represent a table of elements.
    TABLE = 15;

    /// Role used to represent a grid. For example, an element with the
    /// aria-grid role.
    GRID = 16;

    /// Role used to represent the row of a table.
    TABLE_ROW = 17;

    /// Role used to represent the cell of a table or grid.
    CELL = 18;

    /// Role used to represent a column header. For example, an element with
    /// the html tag <th>.
    COLUMN_HEADER = 19;

    /// Role used to represent an aria-rowgroup-like element.
    ROW_GROUP = 20;

    /// Role used to represent a paragraph of text.
    PARAGRAPH = 21;

    // A special type of input text field that represents a search box.
    SEARCH_BOX = 22;

    // Role used to represent a text field with an associated combo box (e.g. a
    // dropdown menu).
    TEXT_FIELD_WITH_COMBO_BOX = 23;

    // Role used to represent an aria-rowheader-like element.
    ROW_HEADER = 24;
};

/// The possible origins of a label.
type LabelOrigin = strict enum {
    /// The node does not have a label yet.
    UNITIALIZED = 1;
    /// An attribute of this element in the runtime UI explicitly sets its
    /// label. For example, an element with aria-label.
    ATTRIBUTE = 2;
    /// An attribute of this element in the runtime UI explicitly sets its
    /// label to be empty.
    ATTRIBUTE_EMPTY = 3;
    /// This label serves as the caption for a table-like element. Because some
    /// assistive technology have special modes to deal with tables, a runtime
    /// should mark its label with this type of origin so that users know what
    /// the table is about when they navigate in the table mode. For example,
    /// a <caption> html tag sets the label.
    CAPTION = 4;
    /// This node receives its label from the contents present in the
    /// application. For example, text from a web page becomes the label of
    /// this node.
    CONTENTS = 5;
    /// An element that can receive user entered value and has a suggested
    /// input. For example, the placeholder attribute on an html input field.
    PLACEHOLDER = 6;
    /// Another element provides the label for this element. For example, via
    /// aria-labeledby.
    RELATED_ELEMENT = 7;
    /// This element's label is represented by a visual tooltip. For example,
    /// as if from a <title> html tag.
    TITLE = 8;
    /// The label comes from an user-entered value.
    VALUE = 9;
};

/// Slider / range control attributes.
type RangeAttributes = table {
    /// The minimum value a range control element can take.
    1: min_value float32;
    /// The maximum value a range control element can take.
    2: max_value float32;
    /// The step delta the element applies when the action DECREMENT or
    /// INCREMENT are invoked.
    3: step_delta float32;
};

/// Set attributes that control how an element is connected to others in the
/// same set. For example, a group of radio buttons in html containing the same
/// name attribute are part of the same set.
type SetAttributes = table {
    /// Size of the set.
    1: size uint32;
    /// Element index in the set, starting from one.
    2: index uint32;
    /// Node ids of other elements in this set.
    3: set_element_ids vector<uint32>:MAX_SET_ELEMENTS;
};

/// Attributes that control how a table cell node is interpreted.
type TableAttributes = table {
    /// The number of columns this table cell spans.
    @deprecated("Use TableCellAttributes for cell nodes instead")
    1: column_span uint32;

    /// The number of rows this table cell spans.
    @deprecated("Use TableCellAttributes for cell nodes instead")
    2: row_span uint32;

    /// Number of rows in this table.
    3: number_of_rows uint32;

    /// Number of columns in this table.
    4: number_of_columns uint32;

    /// Node ids of the table's column headers.
    5: column_header_ids vector<uint32>:MAX_SET_ELEMENTS;

    /// Node ids of the table's row headers.
    6: row_header_ids vector<uint32>:MAX_SET_ELEMENTS;
};

/// Attributes that control how a table row node is interpreted.
type TableRowAttributes = table {
    /// Table row index.
    1: row_index uint32;
};

/// Attributes that control how a table cell is interpreted.
type TableCellAttributes = table {
    /// Row-index of this cell.
    1: row_index uint32;

    /// Column-index of this cell.
    2: column_index uint32;

    /// The number of rows this table cell spans.
    3: row_span uint32;

    /// The number of columns this table cell spans.
    4: column_span uint32;
};

/// An attribute is an essential property to describe an element. Unlike states, attributes do not
/// change over the life of an element.
/// Example: A button with a label attribute 'ok' should never change to 'cancel', as this is not
/// the same element.
type Attributes = table {
    /// The primary label for an element. If longer than MAX_LABEL_SIZE the client is responsible
    /// for truncating the label.
    1: label string:MAX_LABEL_SIZE;

    /// The secondary label for an element. If longer than MAX_LABEL_SIZE the client is responsible
    /// for truncating the label.
    2: secondary_label string:MAX_LABEL_SIZE;

    /// A description of what the secondary action on a node (equivalent to long press or right click) should do.
    3: secondary_action_description string:MAX_LABEL_SIZE;

    /// The range attributes are filled if the element is a slider / a range
    /// control.
    4: range RangeAttributes;

    /// Set attributes are filled if the element is part of some type of set.
    /// For example, radio buttons that are related are part of the same set.
    5: set SetAttributes;

    /// The list attributes should be filled if the node has the LIST role.
    /// Note that only `size` and `set_element_ids` should be filled.
    6: list_attributes SetAttributes;

    /// The list element attributes should be filled if the node has a
    /// LIST_ELEMENT role and descends from a node with a LIST role.
    /// Note that only `index` should be filled.
    7: list_element_attributes SetAttributes;

    /// The hierarchical level of an element. For example, a header can be of
    /// level 1 to 6 in html or markdown.
    8: hierarchical_level uint32;

    /// The table attributes are filled when the element is a table.
    9: table_attributes TableAttributes;

    /// The origin of the label of this element.
   10: label_origin LabelOrigin;

    /// Whether the element is part of a virtual keyboard. For example, a key
    /// on an onscreen keyboard.
   11: is_keyboard_key bool;

    /// The table row attributes are filled when the element is a table row.
   12: table_row_attributes TableRowAttributes;

    /// The table cell attributes are filled when the element is a table cell.
   13: table_cell_attributes TableCellAttributes;
};

/// Represents the state of a UI checkbox.
type CheckedState = strict enum {
    /// Used when no data is entered or the element is not a check box.
    NONE = 1;
    /// Checked
    CHECKED = 2;
    /// Unchecked
    UNCHECKED = 3;
    /// Indeterminate state
    MIXED = 4;
};

/// Represents the state of a UI toggle switch.
type ToggledState = strict enum {
    /// Toggle switch is on.
    ON = 1;
    /// Toggle switch is off.
    OFF = 2;
    /// Toggle switch is in Indeterminate state.
    INDETERMINATE = 3;
};

/// A state is a dynamic property of an element that may change in response to
/// user action or automated processes. Thus, they are different from attributes
/// in an important point, which is frequency of change.
type States = table {
    /// DEPRECATED
    1: checked bool;

    /// State of a checkbox.
    /// This field is mutually exclusive with ToggledState.
    2: checked_state CheckedState;

    /// Whether the element is currently selected.
    3: selected bool;

    /// Whether the element is currently hidden or marked invisible by the framework.
    4: hidden bool;

    /// The user-entered value of the element, if applicable. If longer than MAX_VALUE_SIZE the
    /// client is responsible for truncating.
    5: value string:MAX_VALUE_SIZE;

    /// If the element is a slider or a range control, this field contains the
    /// current value. Note that this is not the same as the value field above,
    /// as this is generated by the client and just adjusted by the user.
    6: range_value float32;

    // If the element is a scrollable viewport, this field contains the x and
    // y offsets within this node's coordinate space to apply to the children.
    // This offsetting is used to position the children within the viewport to
    // reflect the current scrolling of the element.   There are no constraints
    // on these values other than they must be finite.
    7: viewport_offset fuchsia.ui.gfx.vec2;

    /// State of a toggle switch.
    /// This field must only be set if the element is a toggle switch element
    /// and is mutually exclusive with CheckedState.
    8: toggled_state ToggledState;

    /// Whether this element is focusable in the UI. Note that this is not the
    /// a11y focus, but the input focus.
    9: focusable bool;

    /// Whether this element has the input focus. This corresponds to the
    /// system focus. Only one element can have this value set. The behavior is
    /// undetermined if more than one node sets this value to 'true'.
   10: has_input_focus bool;
};

/// The Node represents a semantic element on an interface. This may
/// be a button, a text field, a checkbox or any element that has a relevant
/// semantic meaning so that assistive technology can understand the current UI.
type Node = table {
    /// Unique ID that represents a node in a particular UI.
    /// Zero is assumed to be the root node and the only entry point to the tree.
    /// No forest is allowed.
    1: node_id uint32;

    /// Role of this element, e.g. button, checkbox, etc.
    2: role Role;

    /// A table of states of this object, e.g. checked, editable, etc.
    3: states States;

    /// A table of attributes of this node.
    4: attributes Attributes;

    /// A list of actions that can be performed on this node.
    5: actions vector<Action>:100;

    /// The list of child IDs of this node, in traversal order. Runtimes supplying semantic tree
    /// information are responsible for ensuring the tree does not contain cycles. Each node may
    /// have only one parent.
    6: child_ids vector<uint32>:MAX_FAN_OUT;

    /// Local bounding box of this element.
    7: location fuchsia.ui.gfx.BoundingBox;

    /// Transform from this node's coordinate space to its container's space. 4x4 for compatibility
    /// with scenic.  This matrix is required to have the form
    ///
    ///  [ Sx   0    0    Tx ]
    ///  [ 0    Sy   0    Ty ]
    ///  [ 0    0    Sz   Tz ]
    ///  [ 0    0    0    1  ]
    ///
    ///  where Sx, Sy, and Sz are scale factors and Tx, Ty, Tz are the translation factors for
    ///  the x, y, and z components.
    ///
    /// TODO(fxb.dev/87181): Deprecate.
    8: transform fuchsia.ui.gfx.mat4;

    /// NOTE: We are deprecating `transform` in favor of `node_to_container_transform`. Clients
    /// must NOT set both fields.
    ///
    /// Transform from this node's coordinate space to its container's space. If the `container_id`
    /// field is set, then that id specifies the container node. Otherwise, this node's parent is
    /// the container node.
    ///
    /// Additionally, if `container_id` is set, the fuchsia accessibility manager will
    /// post-translate this node's coordinate space by its container's `location.min` after
    /// applying `node_to_container_transform` when converting to the container's coordinate space.
    /// If `container_id` is unset, this post-translation will NOT be applied.
    ///
    /// 4x4 for compatibility with scenic.  This matrix is required to have the form:
    ///
    ///  [ Sx   0    0    Tx ]
    ///  [ 0    Sy   0    Ty ]
    ///  [ 0    0    Sz   Tz ]
    ///  [ 0    0    0    1  ]
    ///
    ///  where Sx, Sy, and Sz are scale factors and Tx, Ty, Tz are the translation factors for
    ///  the x, y, and z components.
   10: node_to_container_transform fuchsia.ui.gfx.mat4;

    /// Node ID of the ancestor of this node that is used as the target of |transform|.
    /// If not present, this is interpreted as this node's parent.
    9: container_id uint32;
};