# yaml-language-server: $schema=../schema/yaml-form.schema.json
# This is a sample YAML definition for the form.
# Texts after # are comments and are ignored.

title: "Test Form" # title of form
# id: "test_form" # optional; echoed into the submit payload as form.id
# version: "1.0" # optional; echoed into the submit payload as form.version
# autosave: false # optional; default true. Answers are autosaved to the
# browser's localStorage and restored when the same URL is reopened; a
# successful submit clears the draft. Set id (and bump version on changes)
# when autosave matters. Consider false for shared/kiosk devices.
description: |
  Description of form
  You can use multiple line text
  URLs are auto linked -> https://sample.com/
# description of form. This is optional.

# Define actions to be executed when the form is submitted.
# This is an array of action objects (a single mapping is also accepted).
# Available types are:
# - log: Log the payload to the browser console. Useful for testing.
# - post: Send the payload to the specified URL as JSON via POST.
# - mailto: Open the user's mail client with the answers pre-filled in the body.
#   (The user sends the mail manually; long forms may hit mailto URL length limits.)
actions:
  - type: log
  # - type: post
  #   url: "https://example.com/api/submit"
  # - type: mailto
  #   to: "example@example.com"
  #   subject: "Form submission" # optional; defaults to the form title

# Define actions to be executed after the form is submitted. This is optional.
post_submit:
  # message is the message to be displayed after the form is submitted.
  message: "Thank you for your submission."

# Define form items as array of items.
# Available types are:
# - constant: Constant value. This is not editable.
# - short_text: Short text input.
# - long_text: Long text input.
# - choice: Single choice or multiple choice.
# - choice_table: Single choice or multiple choice table.
# - rubric: Rubric table with per-cell descriptors.
# If you do not specify the type, it will be treated as a short_text.
# Every item requires a unique "id"; it is the key in the submitted data
# and the key referenced from visible_when rules.
items:
  - type: "constant" # type of item. This is required.
    title: "constant_sample" # title of item. This is required.
    id: "constant_test" # id of item. This is required and must be unique in the form.
    value: "value" # value of item. This is required only in constant type.

  # A constant can opt in to URL-parameter override and static hiding.
  # Opening the form as form.html?respondent=r042 puts "r042" into the submit
  # payload without an on-screen field — per-respondent distribution URLs.
  # (Disclose to respondents when distribution URLs identify them.)
  - type: "constant"
    title: "Respondent"
    id: "respondent"
    value: "anonymous" # fallback when the URL parameter is absent
    from_url: true # optional; allow ?respondent=... to override the value. Default: false.
    hidden: true # optional; render nothing for this item. constant only. Default: false.

  - type: "short_text"
    id: "id_sample"
    title: "Short Text"
    required: true # This item is required. This is optional. It is false by default.
    description: "description for a item" # description of item. This is optional.

  - type: "short_text"
    id: "email_sample"
    title: "Email"
    input_type: "email" # optional: email | tel | url | number. Sets the HTML input
    # type so browsers offer a matching keyboard and autofill. Default: plain text.
    autocomplete: "email" # optional: HTML autocomplete token(s) for autofill (WCAG 1.3.5)

  - type: "long_text"
    id: "long_text_sample"
    title: "Long Text"

  - type: "choice"
    id: "single_choice"
    title: "Single Choice"
    # choices is array of choice items.
    choices:
      - "option1"
      - "option2"
      - "option3"
      - "option4"

  - type: "choice"
    id: "multiple_choice"
    title: "Multiple Choice"
    multiple: true # This item is multiple choice. This is optional. It is false by default.
    choices:
      - "option1"
      - "option2"
      - "option3"
      - title: "option4"
        value: "value4"  # You can specify the value of the choice item.

  - type: "choice_table"
    id: "choice_table_sample"
    title: "Choice Table"
    # items is array of choice items. This is required. This represents the rows
    # of the table: the individual questions sharing one scale.
    # Answers are submitted as { <row key>: <selected value> } under this item's id;
    # the row key is the row's "id" if specified, otherwise its title (which then
    # must satisfy the same constraints as an id). Keys must be unique within the item.
    items:
      - "sub_question1"
      - "sub_question2"
      - "sub_question3"
      - "sub_question4"
      - "sub_question5"
      - "sub_question6"
      - "sub_question7"
      - { title: "sub_question8", id: "sq8" } # id overrides the key for this row (unique within this item).
    # choices is array of choice items. This is required. This represents the
    # columns of the table: the shared scale.
    choices:
      - "scale1"
      - "scale2"
      - "scale3"
      - "scale4"
      - "scale5"
      - "scale6"
      - "scale7"
      - "scale8"
      - "scale9"
      - "scale10"

  - type: "choice_table"
    id: "multiple_choice_table"
    title: "Multiple Choice Table"
    multiple: true # Multiple selections allowed per row; the answer for each
    # row is submitted as an array, e.g. { sub_question1: ["scale1", "scale3"] }.
    items:
      - "sub_question1"
      - "sub_question2"
      - "sub_question3"
      - "sub_question4"
    choices:
      - "scale1"
      - "scale2"
      - "scale3"
      - "scale4"
      - "scale5"
      - "scale6"
      - "scale7"
      - "scale8"

  # --- Conditional Visibility (visible_when) ---
  # You can conditionally show/hide items using the visible_when field.
  # The item is shown only when the expression evaluates to true.
  # The expression references other items by their id. Answers of choice_table
  # and rubric items are referenced with dotted keys: <item_id>.<row_or_criterion_id>.
  #
  # The rule syntax follows @ncukondo/dynamic-form-rules:
  #   https://github.com/ncukondo/dynamic-form-rules
  #
  # Syntax:
  #   Comparison:  id="value"              id<>"value"
  #   Contains:    id includes "value"     id notIncludes "value"
  #   Set:         id in ["a","b","c"]     id notIn ["a","b"]
  #   Regex:       id matches "\d+"        id notMatches "\d+"
  #   Logical:     expr and expr           expr or expr          not expr
  #                ("and" has higher precedence than "or"; parentheses are supported)
  #   Multi-key:   anyOf(id1,id2)="x"      allOf(id1,id2)="x"    noneOf(id1,id2)="x"
  #
  # Quoting: keys/values may be unquoted if they contain only safe characters
  # (no , = ( ) < > [ ] quotes or whitespace); otherwise use single or double
  # quotes. A quote inside a quoted value is escaped by doubling (e.g. 'it''s ok').

  - type: "choice"
    id: "has_other"
    title: "Do you have other comments?"
    choices: ["yes", "no"]

  - type: "long_text"
    id: "other_comments"
    title: "Other Comments"
    visible_when: 'has_other = "yes"' # shown only when "yes" is selected above

  # --- Rubric ---
  # A rubric is a choice_table whose rows carry per-cell descriptor text.
  # The structure is the same as choice_table (items = rows, choices = columns).
  # Differences:
  # - Each row has "descriptors": one text per column, in column order.
  #   The count must match the number of choices.
  # - multiple is not allowed.
  # - comment_per_row (optional) adds a free-text box under each row.
  # Answers are submitted like choice_table:
  #   { presentation_rubric: { clarity: "2", evidence: "3" } }
  # and referenced from visible_when with dotted keys:
  #   presentation_rubric.clarity in ["1","2"]
  - type: "rubric"
    id: "presentation_rubric"
    title: "Presentation Rubric"
    required: true # every row must have a selection
    choices: # columns: the shared scale. Same rules as choice_table choices.
      - { title: "Novice", value: "1" }
      - { title: "Competent", value: "2" }
      - { title: "Expert", value: "3" }
      # There is no allow_na field. To offer "not applicable", add it as a
      # regular column (it applies to all rows and needs a descriptor in each):
      # - { title: "N/A", value: "NA" }
    items: # rows: the criteria. Key rules are the same as choice_table rows.
      - id: "clarity"
        title: "Clarity"
        descriptors:
          - "Hard to follow; main point unclear"
          - "Mostly clear with minor gaps"
          - "Consistently clear and well structured"
      - id: "evidence"
        title: "Use of evidence"
        descriptors:
          - "Claims are unsupported"
          - "Some claims supported by evidence"
          - "All claims well supported and cited"
    comment_per_row: false # optional: adds a free-text box under each row.
    # When true, each row's answer becomes { value, comment } instead of the
    # bare value (comment omitted when empty), referenced from visible_when
    # as presentation_rubric.clarity.value etc.

  # A rubric criterion can be referenced from visible_when with a dotted key:
  - type: "long_text"
    id: "clarity_feedback"
    title: "Advice for improving clarity"
    visible_when: 'presentation_rubric.clarity in ["1","2"]'