// 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.ui.remotewidgets;

using fuchsia.fonts;

/// Defines special actions that are used on Values to control QuickUi
/// navigation or provide extra semantics to actions associated with them.
type QuickAction = strict enum {
    /// Can be set on a button spec. Tells the client to navigate to a details
    /// view reserved exclusively for specs from this server.
    DETAILS = 0x80000000;
    /// Can be set on a button spec. Tells the client to return to the previous
    /// view and discard any changes in flight.
    CANCEL = 0x40000000;
    /// Can be set on a button spec. Tells the client to return to the previous
    /// view and send all changes in flight to the server.
    SUBMIT = 0x20000000;
    /// Can be set on a text spec used in a ListValue. Tells the client to
    /// consider the associated list item as selected.
    SELECT = 0x10000000;
};

/// The value to hold these numeric types.
type Number = strict union {
    1: int_value int64;
    2: uint_value uint64;
    3: double_value float64;
};

/// Represents a number type in a ui spec with an associated action.
type NumberValue = struct {
    value Number;
    action int32 = 0;
};

/// Represents a string type in a ui spec with an associated action.
type TextValue = struct {
    text string:64;
    action int32 = 0;
};

/// Represents a button type in a ui spec with an associated action.
type ButtonValue = struct {
    label string:64;
    action int32 = 0;
};

/// Represents a progress indicator type in a ui spec with an associated action.
type ProgressValue = struct {
    // [0..1] inclusive.
    value float32;
    action int32 = 0;
};

/// Represents an input type in a ui spec with an associated action.
type InputValue = struct {
    text string:1024;
    // 0 = multiline. 1 = Default.
    lines int32 = 1;
    action int32 = 0;
};

/// Represents an icon type in a ui spec with an associated action.
type IconValue = struct {
    code_point int32;
    font_family box<fuchsia.fonts.FamilyName>;
    action int32 = 0;
};

/// Represents a grid of strings type in a ui spec with an associated action.
type GridValue = struct {
    columns byte;
    values vector<TextValue>:256;
};

/// Represents a list of strings type in a ui spec.
type ListValue = struct {
    multiselect bool = false;
    popup bool = false;
    title string:128;
    items vector<TextValue>:1024;
};

/// Represents a graph type in a ui spec with an associated action.
type GraphValue = struct {
    // [0..1] inclusive.
    value float32;
    // Unit of progress in the x-axis.
    step int32;
    action int32 = 0;
};

/// Represents a Value that is union of all types.
type Value = strict union {
    1: number NumberValue;
    2: text TextValue;
    3: progress ProgressValue;
    4: button ButtonValue;
    5: input InputValue;
    6: icon IconValue;
    7: grid GridValue;
    8: graph GraphValue;
    9: list ListValue;
};

/// Represents a group of [Value]s with a title.
type Group = table {
    // The title to show for this group.
    1: title string:128;
    // The icon to show for this spec.
    2: icon IconValue;
    // List of [Value] objects that form part of this spec.
    3: values vector<Value>:16;
};

/// Describes a specification of quick UI.
type Spec = table {
    // The title to show for this spec.
    1: title string:128;
    // List of [Group] objects that form part of this spec.
    2: groups vector<Group>:8;
};

/// Defines a protocol for a component to provide specs for building UI for
/// quick settings or notifications, independent of any platform.
@discoverable
protocol QuickUi {
    /// Request [Spec] from the provider. The provider should return Spec
    /// whenever it is ready to. Until then this request remains outstanding,
    /// aka "hanging get". The provider can return completely different set of
    /// status on every invocation. The client can provide an optional [Value]
    /// to allow the provider to customize the returned UI spec. Typically,
    /// this value was part of previous [Spec] and identifies the part of
    /// [Spec] the user interacted with.
    GetSpec(struct {
        value Value:optional;
    }) -> (struct {
        spec Spec;
    });
};