Skip to main content

Documentation Index

Fetch the complete documentation index at: https://ziva.zeleza.ru/llms.txt

Use this file to discover all available pages before exploring further.

​
Ziva Best Practices

Use this checklist when integrating Ziva into production systems. It covers structure, validation, styling, performance and testing.

​
Architecture & code organisation

  • Keep task creation in factories/helpers so queues stay readable.
  • Group tasks by stage and spin up separate queues for each stage (collect → validate → apply). This makes testing and reuse easier.
  • Store references to tasks whose values you need after queue.Run(); their state persists.
  • Call ziva.AutoConfigure() plus language setup (SetDefaultLanguage, SetLanguage) in main() before you start creating queues.

​
Queue management

  • Enable numbering via WithTasksNumbered(true, "[%02d]") for long scenarios; operators orient themselves faster.
  • Disable the final summary (WithOutSummary()) when you already log results elsewhere. Otherwise, add WithSummaryFunction to show key metrics inline.
  • Always provide WithTimeout*() defaults for headless runs (CI, SSH). Pick a fallback that is safe for the workflow.
  • For dynamic flows, assemble a new Queue, push the generated tasks, and run it after the primary queue.

​
Validation & input

  • Keep Description() messages user-friendly — Ziva renders them under the field.
  • Mix built-in validators from DefaultValidators with custom types. Compose them for complex rules and cover them with tests.
  • Combine WithAllowEmpty(true) with validators that tolerate empty strings (for example OptionalEmail).
  • Add a FuncTask right after the input when you need a network check (duplicate email in CRM, external API) and show the outcome to the operator.

​
Styling & localisation

  • Customise error colours with ziva.SetErrorColor to match brand requirements; call ResetErrorColors() after experiments.
  • On constrained terminals combine EnableEmbeddedMode() and EnableASCIIMode() so the output stays legible.

​
Performance & embedded targets

  • Limit completed-task history with the ZIVA_MAX_COMPLETED_TASKS environment variable.
  • Monitor memory via ZIVA_MEMORY_PRESSURE_THRESHOLD and periodically purge the string intern cache using ziva.ClearInternCache() for long-lived CLIs.
  • Use WithViewport(...) for large lists — it keeps the UI responsive and prevents long jumps.
  • Split heavy work into smaller FuncTask steps so users see progress more often.

​
Testing & debugging

  • Unit-test task factories: create the task, simulate messages via Update, and verify the final state/result.
  • Maintain demo queues under examples/ and run them manually. Capture screenshots/GIFs by disabling WithClearScreen(true) when recording.
  • Log critical failures outside of Ziva (e.g. log/zap), especially when queues halt due to WithStopOnError(true).

​
Release-ready checklist

  • Timeouts and default values reviewed.
  • Tasks grouped by stage; layout fits the target terminal width.
  • Validation covers negative cases; complex rules are tested.
  • Colour scheme and localisation conform to product requirements.
  • Embedded devices verified with AutoConfigure() and embedded mode.
Pair these guidelines with the examples section to build reliable and friendly TUIs with Ziva.