# yaml-language-server: $schema=https://raw.githubusercontent.com/jackchuka/mdschema/main/schema.json

# IMPLEMENTATION TIER
# Screen file: screen/<screenName>.md
# TODO: should check existance of screens via CI/CD pipeline

structure:
  - heading:
      expr: "filename == heading"
    children:
      - heading: "## Overview"
        description: |
          Brief description of what this screen does and its purpose in the application.

      - heading: "## Screen Type"
        description: |
          The type of frontend page. Must be one of: Form, ListView, or DetailView.
          - Form: a page with input fields for creating or editing an entity
          - ListView: a page displaying a table of entities with columns
          - DetailView: a page showing details of a single entity with available actions
        required_text:
          - pattern: "(Form|ListView|DetailView)"
            regex: true
        children:
          - heading: "### Form Details"
            description: |
              Details for Form screens. Defines the input fields the user fills in.
            optional: true
            children:
              - heading: "#### Input Fields"
                description: |
                  Table of form fields for the parent entity.
                  - Field Name: display label for the field
                  - Field Type: one of String, Text, Email, Number, Decimal, Boolean, Date, DateTime, Select, MultiSelect, Lookup, MultiLookup, CreatableLookup, Autocomplete
                  - Required (Yes/No): whether the field must be filled
                  - Options / Lookup: for Select/MultiSelect, fixed values (comma-separated) or entity reference (e.g., "Supplier entity → name"). "—" for other types
                tables:
                  - min: 1
                    required_headers:
                      - Field Name
                      - Field Type
                      - Required (Yes/No)
                      - Options / Lookup
              - heading: "#### Line Items"
                description: |
                  Table of fields for repeating child rows (e.g., order lines, invoice lines).
                  Same column format as Input Fields. Only include when the form has a parent-child structure with repeating rows.
                optional: true
                tables:
                  - min: 1
                    required_headers:
                      - Field Name
                      - Field Type
                      - Required (Yes/No)
                      - Options / Lookup
          - heading: "### ListView Details"
            description: |
              Details for ListView screens. Defines the table columns and optional filters.
            optional: true
            children:
              - heading: "#### Required Columns"
                description: |
                  Table of columns displayed in the list.
                  - Column Name: display header for the column
                  - Hideable (Yes/No): whether the user can hide this column
                  - Sort-able (Yes/No): whether the column supports sorting
                  - Filter-able (Yes/No): whether the column can be used as a filter. If Yes, consider adding a corresponding entry in the Filters section
                  - Searchable (Yes/No): whether the column is included in text search
                tables:
                  - min: 1
                    required_headers:
                      - Column Name
                      - Hideable (Yes/No)
                      - Sort-able (Yes/No)
                      - Filter-able (Yes/No)
                      - Searchable (Yes/No)
              - heading: "#### Filters"
                description: |
                  Filter UI specifications for columns or non-visible fields.
                  - Filter Name: display label for the filter
                  - Target Column: which Required Column it filters, or a non-visible field name
                  - Filter Type: one of text-search, select, multi-select, date-range, number-range, boolean
                  - Options / Lookup: for select/multi-select, fixed values (comma-separated) or entity reference (e.g., "Supplier entity → name"). "—" for other types
                optional: true
                tables:
                  - min: 1
                    required_headers:
                      - Filter Name
                      - Target Column
                      - Filter Type
                      - Options / Lookup
          - heading: "### DetailView Details"
            description: |
              Details for DetailView screens. Defines the displayed fields and available actions.
            optional: true
            children:
              - heading: "#### Displayed Fields"
                description: |
                  Bulleted list of fields shown on the detail page (e.g., Name, Email, Status).
                lists:
                  - min: 1
                    type: unordered
                    min_items: 1
              - heading: "#### Available Actions"
                description: |
                  Table of actions available on this screen.
                  - Action: the operation name (e.g., Edit, Close, Delete)
                  - Condition: when the action is available (e.g., "status is DRAFT"), or "—" if always available
                  - Requires Input: parameters the user must provide before execution (e.g., "writeOffRemaining (Boolean), closeReason (String)"), or "—" if none
                  - Confirmation: "dialog" if the action needs a confirmation dialog, or "—" if it executes immediately
                tables:
                  - min: 1
                    required_headers:
                      - Action
                      - Condition
                      - Requires Input
                      - Confirmation

      # Sheets - child screens displayed as side sheets or dialogs
      - heading: "## Sheets"
        description: |
          References to screens displayed as side sheets or dialogs from this screen.
          Each referenced screen must be a separate screen doc file.
          - Trigger: user action that opens the sheet (e.g., "Row click", "Log button")
          - Screen: markdown link to the child screen doc (e.g., "[deal-detail](./deal-detail.md)")
          - Display: "Right Sheet" or "Dialog"
        optional: true
        tables:
          - min: 1
            required_headers:
              - Trigger
              - Screen
              - Display

      - heading: "## Access Control"
        description: |
          Specify the actors that have access to this screen.
          Use links to actor documents (e.g., [buyer-administrator](../actor/buyer-administrator.md)).
        lists:
          - min: 1
            type: unordered

# Link validation
links:
  validate_internal: true
  validate_files: true

# Heading rules
heading_rules:
  no_skip_levels: true
  unique: true
  max_depth: 4