diff --git a/gui.md b/gui.md new file mode 100644 index 0000000..0f2eaa4 --- /dev/null +++ b/gui.md @@ -0,0 +1,234 @@ +# GUI Configuration (`gui`) + +## Introduction + +The `gui` section within the YAML configuration provides metadata specifically tailored for building user interfaces related to Rainlang strategies. It acts as a bridge between the core technical definition of deployments, tokens, orders, etc., and their presentation to an end-user in a graphical application. + +This section dictates how strategy deployments are named, described, and how their configurable parameters (bindings, deposits, token selections) should be rendered as interactive UI elements. It allows for user-friendly labels, descriptions, default values, and predefined options (presets) to simplify the user experience. + +**Note**: While the underlying YAML parser treats all scalar values initially as strings, the application expects these strings to conform to the specified semantic types (e.g., `true` or `false` for Boolean fields) for successful processing. The types listed below refer to these expected semantic types. + +## Top-Level `gui` Object + +The root of the GUI configuration is the `gui:` key. It contains general information about the strategy or set of deployments described in the file. + +```yaml +gui: + name: Fixed limit + description: Fixed limit order strategy + short-description: Buy WETH with USDC on Base. + deployments: + # ... deployment configurations ... +``` + +### Fields + +* `name` + * **Type**: String + * **Required**: Yes + * **Description**: The primary, human-readable name for the overall strategy or configuration presented in the GUI. +* `description` + * **Type**: String + * **Required**: Yes + * **Description**: A more detailed description of the strategy or configuration, intended for display in the GUI. +* `short-description` + * **Type**: String + * **Required**: No + * **Description**: An optional, concise description, potentially used in contexts where space is limited (e.g., list views, tooltips). +* `deployments` + * **Type**: Map + * **Required**: Yes + * **Description**: Contains the specific UI configurations for one or more named deployments. See the [Deployments Map](#deployments-map-deployments) section for details. + +## Deployments Map (`deployments`) + +The `deployments` field under `gui` holds a map where each key is the name of a deployment (which must correspond to a deployment defined elsewhere in the configuration, e.g., under the top-level `deployments:` key) and the value is an object defining the GUI configuration specific to that deployment. + +```yaml +gui: + # ... name, description ... + deployments: + : + # ... configuration for deployment 1 ... + : + # ... configuration for deployment 2 ... + # ... etc ... +``` + +## Deployment Configuration (``) + +Each entry within the `deployments` map defines the specific UI elements and text for a single deployment. + +```yaml +gui: + # ... + deployments: + some-deployment: # This key must match a defined deployment + name: Buy WETH with USDC on Base. + description: Buy WETH with USDC for fixed price on Base network. + short-description: Buy WETH with USDC on Base. + deposits: + # ... deposit items ... + fields: + # ... field items ... + select-tokens: + # ... select token items ... +``` + +### Fields + +* `name` + * **Type**: String + * **Required**: Yes + * **Description**: The name of this specific deployment variation as it should appear in the GUI. +* `description` + * **Type**: String + * **Required**: Yes + * **Description**: A detailed description for this specific deployment variation. +* `short-description` + * **Type**: String + * **Required**: No + * **Description**: An optional, concise description for this deployment variation. +* `deposits` + * **Type**: List of [Deposit Items](#deposit-item) + * **Required**: Yes + * **Description**: Defines the tokens users can deposit into the strategy and provides UI hints like presets. +* `fields` + * **Type**: List of [Field Items](#field-item) + * **Required**: Yes + * **Description**: Defines the user-configurable parameters (bindings) for the strategy, including labels, descriptions, presets, and defaults. +* `select-tokens` + * **Type**: List of [Select Token Items](#select-token-item) + * **Required**: No + * **Description**: Defines specific tokens that might be selectable in other parts of the UI for this deployment (e.g., choosing an output token if the strategy supports it). + +## Deposit Item + +Each item in the `deposits` list defines a token that can be deposited and optional preset amounts for the UI. + +```yaml +# Example within a deployment's deposits list: +deposits: + - token: token1 # Must match a defined token key + presets: + - "0" + - "10" + - "100" + - "1000" + - "10000" + - token: token2 + # No presets defined for this token +``` + +### Fields + +* `token` + * **Type**: String + * **Required**: Yes + * **Description**: The key referencing a token defined in the top-level `tokens` section. This specifies which token the deposit configuration applies to. +* `presets` + * **Type**: List of Strings + * **Required**: No + * **Description**: An optional list of suggested deposit amounts (as strings) to display as quick options in the UI. The UI will typically show these alongside the primary deposit input field. + +## Field Item + +Each item in the `fields` list defines a user-configurable input field, mapping it to an underlying Rainlang binding. + +```yaml +# Example within a deployment's fields list: +fields: + - binding: binding-1 # The corresponding binding in the Rainlang source + name: Field 1 name + description: Field 1 description + presets: + # ... preset items for this field ... + default: some-default-value + - binding: binding-2 + name: Field 2 name + description: Field 2 description + # No presets for this field + show-custom-field: true # Explicitly allow custom input +``` + +### Fields + +* `binding` + * **Type**: String + * **Required**: Yes + * **Description**: The name of the binding in the associated Rainlang source code that this field provides the value for. +* `name` + * **Type**: String + * **Required**: Yes + * **Description**: The human-readable label displayed for this input field in the GUI. +* `description` + * **Type**: String + * **Required**: No + * **Description**: An optional, longer description or help text displayed for this field, potentially as a tooltip or helper text. +* `presets` + * **Type**: List of [Preset Items](#preset-item) + * **Required**: No + * **Description**: An optional list of predefined values the user can select for this field. +* `default` + * **Type**: String + * **Required**: No + * **Description**: An optional default value (as a string) to pre-populate the input field with. +* `show-custom-field` + * **Type**: Boolean + * **Required**: No + * **Description**: Controls whether the user is presented with a free-form input field in addition to any defined presets. If `false`, the user might only be able to select from the presets. If `true` or omitted, a custom input field is typically shown. + +## Preset Item + +Each item in a field's `presets` list defines a single predefined option for that field. + +```yaml +# Example within a field's presets list: +presets: + - name: Preset 1 Name # Optional name for the preset + value: "0x1234567890abcdef1234567890abcdef12345678" + - value: "false" # Preset without an explicit name + - name: Preset 3 Name + value: "some-string" +``` + +### Fields + +* `name` + * **Type**: String + * **Required**: No + * **Description**: An optional label for the preset option shown in the UI (e.g., in a dropdown or radio button list). If omitted, the `value` itself might be displayed. +* `value` + * **Type**: String + * **Required**: Yes + * **Description**: The actual value (as a string) that will be used for the binding if this preset is selected. + +## Select Token Item + +Each item in the optional `select-tokens` list defines a token that might be presented for selection elsewhere in the UI for this deployment. + +```yaml +# Example within a deployment's select-tokens list: +select-tokens: + - key: token1 # Must match a defined token key + name: Optional Display Name for Token 1 + description: Optional description for selection context + - key: token2 + # Uses default token name/symbol from token definition +``` + +### Fields + +* `key` + * **Type**: String + * **Required**: Yes + * **Description**: The key referencing a token defined in the top-level `tokens` section. +* `name` + * **Type**: String + * **Required**: No + * **Description**: An optional override for the token's display name specifically within this selection context. If omitted, the GUI would likely use the `label` or `symbol` from the main token definition. +* `description` + * **Type**: String + * **Required**: No + * **Description**: An optional description providing context for why this token is selectable here. +