Workflow UI templates
=====================

RAFT browser tools can be customized by workflow-owned UI template files in
the workflow configuration repository. These templates let workflow maintainers
control what the manifest generator and report viewer show without requiring a
RAFT release for every workflow-specific UI change.

Template locations
------------------

For a workflow configuration repository such as:

.. code-block:: text

  workflow-configs/lens/lens-human/lens-human-fastqs/

RAFT looks for manifest templates in this order:

.. code-block:: text

  lens.human.fastqs.manifest-ui.json
  manifest-ui.json

RAFT looks for report templates in this order:

.. code-block:: text

  lens.human.fastqs.report-ui.json
  report-ui.json

The input-specific filename is preferred. The generic filename is useful when
the same UI behavior applies to every input mode for a workflow.

If no workflow-owned template is available, RAFT falls back to packaged generic
defaults.

Manifest template
-----------------

The manifest template controls manifest columns, sample types, workflow labels,
and workflow-level sample requirements.
RAFT also uses this file for CLI manifest validation when
``raft check-manifest`` can auto-detect a single workflow template from a
project or when ``--manifest-ui-template`` is provided explicitly. The CLI uses
``columns[].required``, ``columns[].allowed_values``, and
``sample_types[].prefix``/``sample_types[].normal`` for structural checks, then
applies additional cross-row checks that are not represented in the UI
template.

A LENS-style example:

.. code-block:: json

  {
    "schema_version": "1.0",
    "name": "LENS manifest",
    "description": "Manifest requirements for LENS tumor antigen discovery.",
    "columns": [
      {"name": "Patient_Name", "label": "Patient name", "required": true},
      {"name": "Run_Name", "label": "Run name", "required": true},
      {"name": "Dataset", "label": "Dataset", "required": true},
      {"name": "File_Prefix", "label": "File prefix", "required": true},
      {
        "name": "Sequencing_Method",
        "label": "Sequencing method",
        "required": true,
        "allowed_values": ["WES", "WXS", "WGS", "RNA-Seq", "RNA"]
      },
      {
        "name": "Normal",
        "label": "Normal",
        "required": true,
        "allowed_values": ["TRUE", "FALSE"]
      },
      {"name": "Group", "label": "Group", "required": false},
      {"name": "Alleles", "label": "Alleles", "required": false}
    ],
    "sample_types": [
      {
        "id": "tumor_dna",
        "label": "Tumor DNA",
        "prefix": "ad-",
        "normal": false,
        "sequencing_method": "WES"
      },
      {
        "id": "normal_dna",
        "label": "Normal DNA",
        "prefix": "nd-",
        "normal": true,
        "sequencing_method": "WES"
      },
      {
        "id": "tumor_rna",
        "label": "Tumor RNA",
        "prefix": "ar-",
        "normal": false,
        "sequencing_method": "RNA-Seq"
      },
      {
        "id": "normal_rna",
        "label": "Normal RNA",
        "prefix": "nr-",
        "normal": true,
        "sequencing_method": "RNA-Seq"
      }
    ],
    "workflows": [
      {
        "value": "lens",
        "label": "LENS",
        "description": "Tumor antigen discovery from tumor DNA, normal DNA, and tumor RNA.",
        "requirements": {
          "normal_dna": true,
          "tumor_dna": true,
          "tumor_rna": true,
          "normal_rna": false
        }
      }
    ]
  }

Manifest template fields
~~~~~~~~~~~~~~~~~~~~~~~~

``columns``
  Defines the manifest columns exported by the generator. Each entry should
  include ``name``. ``label``, ``required``, ``description``, and
  ``allowed_values`` are optional UI hints.

``sample_types``
  Defines selectable sample types and their ``Run_Name`` prefixes. The ``id``
  values should be stable machine-readable names. These IDs are also used in
  workflow ``requirements``.

``workflows``
  Defines workflow choices and sample requirements. Requirements are keyed by
  sample type ``id``.

Report template
---------------

The report template controls the patient-level sections shown by the RAFT
report viewer. RAFT keeps the standard patient sidebar, group navigation, and
collapsible layout behavior. Workflow maintainers customize the main report
sections, labels, renderer hints, input file patterns, controls, and optional
table columns. Workflows do not need to produce pMHC data; QC-only and generic
table-based reports are supported.

A minimal LENS-style example:

.. code-block:: json

  {
    "schema_version": "1.0",
    "name": "LENS report",
    "description": "Patient-level antigen report and QC review for LENS.",
    "bundle_format": "raft-report-bundle-v1",
    "layout": {
      "navigation": "patients",
      "group_navigation": true,
      "collapsible_sidebar": true
    },
    "sections": [
      {
        "id": "report",
        "label": "Report",
        "renderer": "lens_antigen_report",
        "source": "lens",
        "default": true,
        "patterns": ["*.report.tsv", "*report*.tsv"],
        "controls": {
          "show_filters": true,
          "show_visualizations": true,
          "show_table": true,
          "show_cards": true
        },
        "table": {
          "columns": [
            {"key": "peptide", "label": "Peptide", "format": "text"},
            {"key": "allele", "label": "Allele", "format": "text"},
            {"key": "priority_score_maximum", "label": "Max Priority Score", "format": "float"},
            {"key": "mhcflurry_2.1.1.aff", "label": "MHCFlurry Aff", "format": "float"},
            {"key": "ccf", "label": "CCF", "format": "float"},
            {"key": "vaf", "label": "VAF", "format": "float"},
            {"key": "tpm", "label": "Log2(TPM)", "format": "log2"},
            {"key": "antigen_source", "label": "Source", "format": "text"}
          ]
        }
      },
      {
        "id": "qc",
        "label": "QC",
        "renderer": "qc_summary",
        "source": "qc"
      }
    ]
  }

Generic table example:

.. code-block:: json

  {
    "schema_version": "1.0",
    "name": "Somatic variation report",
    "description": "Somatic variant calls and run-level QC.",
    "bundle_format": "raft-report-bundle-v1",
    "sections": [
      {
        "id": "somatic_variants",
        "label": "Somatic variants",
        "renderer": "table",
        "default": true,
        "patterns": ["*somatic*.tsv"],
        "table": {
          "columns": [
            {"key": "chrom", "label": "Chrom", "format": "text"},
            {"key": "pos", "label": "Position", "format": "int"},
            {"key": "gene", "label": "Gene", "format": "text"},
            {"key": "effect", "label": "Effect", "format": "text"},
            {"key": "vaf", "label": "VAF", "format": "float"}
          ]
        }
      },
      {
        "id": "qc",
        "label": "QC",
        "renderer": "qc_summary",
        "source": "qc"
      }
    ]
  }

QC-only example:

.. code-block:: json

  {
    "schema_version": "1.0",
    "name": "HLA typing QC",
    "description": "Review HLA typing outputs and quality-control metrics.",
    "bundle_format": "raft-report-bundle-v1",
    "sections": [
      {
        "id": "qc",
        "label": "QC",
        "renderer": "qc_summary",
        "source": "qc",
        "default": true
      },
      {
        "id": "files",
        "label": "Files",
        "renderer": "file_index",
        "patterns": ["*"]
      }
    ]
  }

Report template fields
~~~~~~~~~~~~~~~~~~~~~~

``bundle_format``
  Identifies the report bundle format the viewer expects. Current RAFT bundles
  use ``raft-report-bundle-v1``.

``layout``
  Declares standard viewer layout expectations. The current viewer always uses
  patient navigation on the left, supports patient groups, and lets users
  collapse the sidebar.

``sections``
  Defines patient-level tabs. Each section should define a stable ``id`` and
  display ``label``.

``renderer``
  Selects how a section is displayed. Supported values are ``table`` for
  generic TSV/TXT tables, ``qc_summary`` for built-in QC summaries,
  ``file_index`` for a list of bundle files, and ``lens_antigen_report`` for
  the LENS-specific pMHC report.

``patterns``
  Optional file globs used by ``table`` and ``file_index`` sections. For
  example, ``["*somatic*.tsv"]`` restricts a table section to matching bundle
  files. If omitted, all loaded TSV/TXT report files are eligible.

``controls``
  Optional controls for ``lens_antigen_report`` sections. Set ``show_filters``,
  ``show_visualizations``, ``show_table``, or ``show_cards`` to ``false`` to
  hide that part of the LENS report section.

``table.columns``
  Optional table column list for ``table`` and ``lens_antigen_report`` sections.
  Each column needs ``key`` and ``label``. If omitted for a generic ``table``
  section, RAFT infers columns from the first loaded row. Supported ``format``
  values are ``text``, ``string``, ``float``, and ``log2``.

.. note::

   The report viewer is section-driven. Use ``lens_antigen_report`` only when
   the workflow emits LENS-style pMHC rows. Other workflows should usually start
   with ``table``, ``qc_summary``, and ``file_index`` sections.

Testing templates
-----------------

To test workflow-owned templates locally:

1. Add the template files to the workflow configuration repository.
2. Run ``raft run`` or ``raft run-demo`` for the workflow and version that
   should use the templates.
3. Open the manifest generator or report viewer through RAFT.
4. Confirm that workflow labels, sample types, requirements, and report bundle
   behavior match the template.

For hosted UI testing, make sure the template files are committed to the public
workflow configuration repository. The hosted manifest generator can fetch
``manifest-ui.json`` directly from GitLab when the local RAFT API is not
available.