// Copyright 2018 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.modular;

using fuchsia.mem;

/// StoryCommands are POD structures that describe the set of operations that
/// can be performed on a story by components outside the modular framework. All commands are:
///
///   (1) Scoped to a single story
///   (2) Idempotent: issuing the same command twice yields the same result
///   (3) Symmetrical with observation: the same structures are used to describe
///       operations to watchers of a story (through SessionWatcher) as are used
///       to control a story.
union StoryCommand {
    /// Sets the focus state of the story to `set_focus_state.focused`.
    1: SetFocusState set_focus_state;

    /// Adds a Mod.
    2: AddMod add_mod;

    /// Removes an existing Mod.
    3: RemoveMod remove_mod;

    /// Sets the value of a Link.
    /// DEPRECATED. This command is a no-op.
    4: SetLinkValue set_link_value;

    /// Brings focus to a mod.
    5: FocusMod focus_mod;

    /// Updates the kind_of_proto_story option in a story.
    /// DEPRECATED. This command is a no-op.
    6: SetKindOfProtoStoryOption set_kind_of_proto_story_option;
};

struct SetFocusState {
    bool focused;
};

/// Adds a mod described by `intent` to the story with name `mod_name`. If
/// `mod_name` already exists in the story, the mod is updated.
struct AddMod {
    /// The name of the mod within the story. The mod's name acts as the unique
    /// ID of the mod, scoped to the story in which it is contained. Since
    /// AddMod is reused for observation and mod names are vector<string>
    /// inside the framework, they are vector<string> here as well.
    ///
    /// Clients should treat the full vector as a single opaque value.
    ///
    /// Clients should provide `mod_name_transitional` instead.
    /// If both are provided, `mod_name` is ignored.
    ///
    // TODO(MF-148): Convert to string
    vector<string> mod_name;

    /// The name of the mod within the story. This should be used instead of
    /// `mod_name`. If provided, it is equivalent to passing `mod_name` with
    /// a single item. If both are provided, `mod_name` is ignored.
    ///
    // TODO(MF-148): Remove
    string? mod_name_transitional;

    Intent intent;

    /// `surface_relation` defines the visual relationship between this mod and the
    /// mod at `surface_parent_mod_name`.
    SurfaceRelation surface_relation;
    vector<string>? surface_parent_mod_name;
};

/// Removes the mod under `mod_name` from the story.
struct RemoveMod {
    /// The name of the mod within the story.
    ///
    /// Clients should provide `mod_name_transitional` instead.
    /// If both are provided, `mod_name` is ignored.
    ///
    // TODO(MF-148): Convert to string
    vector<string> mod_name;

    /// The name of the mod within the story. This should be used instead of
    /// `mod_name`. If provided, it is equivalent to passing `mod_name` with
    /// a single item. If both are provided, `mod_name` is ignored.
    ///
    // TODO(MF-148): Remove
    string? mod_name_transitional;
};

/// Sets the value of link at `path` to `value`.
struct SetLinkValue {
    LinkPath path;
    fuchsia.mem.Buffer? value;
};

/// Instructs the session shell to focus the mod under `mod_name`.
struct FocusMod {
    /// The name of the mod within the story.
    ///
    /// Clients should provide `mod_name_transitional` instead.
    /// If both are provided, `mod_name` is ignored.
    ///
    // TODO(MF-148): Convert to string
    vector<string> mod_name;

    /// The name of the mod within the story. This should be used instead of
    /// `mod_name`. If provided, it is equivalent to passing `mod_name` with
    /// a single item. If both are provided, `mod_name` is ignored.
    ///
    // TODO(MF-148): Remove
    string? mod_name_transitional;
};

/// Updates the kind_of_proto_story option in a story.
struct SetKindOfProtoStoryOption {
    bool value;
};