// Copyright (C) 2026 Danilo M. <danix@danix.xyz>
//
// This program is free software; you can redistribute it and/or modify
// it under the terms of the GNU General Public License version 2 as
// published by the Free Software Foundation.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU General Public License for more details.

import QtQuick

// What a module declares to the drawer.
//
// A module provides a tile, a page, both, or neither. A tile with no page
// calls activate() when clicked. A module with neither is a pure background
// service. A module may also own windows outside the drawer entirely, as
// sound does with its OSD.
//
// Nothing here enforces anything: a module is free to do something unusual.
// This file is documentation with defaults.
QtObject {
    // Identifies the module to IPC: `ipc call drawer open <name>`.
    required property string name

    // Shown on the tile. A Nerd Font glyph.
    property string icon: ""

    // Label under the icon. Defaults to the name, capitalised.
    property string label: name.charAt(0).toUpperCase() + name.slice(1)

    // Declarative metadata: whether this module's service is meant to run
    // while the drawer is closed. The drawer does not read or enforce it, the
    // module implements its own lifetime. Pages are lazily loaded either way.
    property bool alwaysActive: false

    // Whether the tile should render in its active accent. Default false.
    property bool active: false

    // Whether the page lives in the settings window rather than the drawer:
    // things set once and left alone. Such a module has no tile by default.
    property bool settings: false

    // The heading a settings page is listed under in the window's sidebar.
    // Groups appear in the order their first module is declared.
    property string group: ""

    // Words the settings window's search matches besides the label: the
    // settings buried inside the page, which is not loaded until opened.
    property list<string> keywords: []

    // The rows inside a settings page, for the search: [{text, key}]. key is
    // the objectName of the row in the page, which the window scrolls to and
    // highlights. Kept by the module because the page is not loaded until
    // opened; refresh() rereads it, and the window calls it on open.
    property var searchItems: []
    function refresh() {}

    // Whether the drawer's grid shows a tile. False for a module reached
    // some other way: the user page opens from the drawer's header row.
    property bool tiled: !settings

    // Rendered inside the tile, below the icon: a short state line. Null for
    // a tile that says nothing beyond its label.
    property Component tileContent: null

    // The full-height page behind the tile. Null means the tile is
    // fire-and-forget and activate() is called instead.
    property Component page: null

    // What a tile with no page does when clicked.
    function activate() {}
}