docs/embed-va.md

@@ -69,6 +69,10 @@ Repeat the parameter to add mappings.  A report with two tabs, each holding its
 | Tab 1 | `...?embed=va&va_parmap=REGION_TAB1-REGION` |
 | Tab 2 | `...?embed=va&va_parmap=REGION_TAB2-REGION` |
 
+The applied filter is visible in the editor, above the grid - here the parameter `DROPDOWN_TAB1` filtering `SOME_DROPDOWN`, which is not its name:
+
+![A va_parmap mapping filtering a column](img/va-parmap-filtered.png)
+
 The mapping is per parameter, and additive:
 
 - a mapped parameter always filters the column it names; that column's type in the table decides how the value is formatted, exactly as for a name match
@@ -79,7 +83,25 @@ The mapping is per parameter, and additive:
 - a column name that is not a plain SAS name is ignored
 - the mapping applies to filtering only; which columns the grid displays still follows the columns VA sends
 
-If an entry cannot be used the editor shows a warning banner above the grid naming the parameter, the column and the table - for example when the column is not in the table being opened, or the entry is not in the `parameter-column` form.  The parameter is then ignored rather than falling back to the name match, so a typo never silently filters the wrong column, and the banner is what distinguishes "the mapping is wrong" from a view that simply has no filter.
+## When a mapping cannot be used
+
+A wrong mapping would otherwise look like a working filter over the whole table, so the editor puts a banner above the grid naming the parameter, the column, the table, and what to change:
+
+![The va_parmap warning banner](img/va-parmap-banner.png)
+
+Each line names one cause, and the parameter it concerns is skipped rather than falling back to the name match - a typo never silently filters the wrong column:
+
+| What the banner says | What it means |
+|---|---|
+| `is not a column of <libref>.<table>` | the mapped column does not exist in the table being opened |
+| `is not a date or datetime column` | a date anchor (`ADD`/`RANGE`) was applied to a column that holds something else |
+| `VA is not sending` | no message has named that parameter - usually a spelling mistake in the parameter side of the entry |
+| `all filter <COLUMN> ... different values will show no rows` | two parameters map to one column with different values, so the AND can never match |
+| `a range needs one value` | a `RANGE` mapping was sent several values - one `BETWEEN` carries one period |
+| `N of its M values was not a date` | part of a multi-value parameter could not be read as a date, so only the rest is applied |
+| `was ignored: it needs a "-"` / `is not a transform` | the entry itself is malformed |
+
+The banner is shown to the report author, inside the report, because that is where the entry is edited: the only fix available from the editor is to change the `va_parmap` entries in the URL of the Data Controller object.
 
 !!! note
     A parameter label containing `&` must be percent-encoded (`%26`), because `&` separates query parameters.  A space may be written as `+` or `%20`.
@@ -92,7 +114,13 @@ A mapping can resolve the parameter value through a **named date anchor** before
 https://yourserver/DC/#/editor/<library>/<table>?embed=va&va_parmap=SELECTED_DATE-D_DATE:ADD(QUARTER_START,-1)
 ```
 
-A report that sends `SELECTED_DATE = 01OCT2026` then filters `D_DATE` on 2026-10-01 **and** 2026-07-01 - the selected date's quarter, plus the same point one quarter earlier.
+A report that sends `SELECTED_DATE = 27FEB1961` then filters `D_DATE` on 1961-02-27 **and** 1960-10-01 - the selected date, plus the same point one quarter earlier:
+
+In the screenshot below the mapping is `SELECTED_DATE-SOME_DATE:ADD(QUARTER_START,-1)` against the demo table, and the parameter sends 27FEB1961:
+
+![A date anchor applied to the filter](img/va-parmap-transform.png)
+
+The clause carries both values, so the row for the selected date and the row for the previous quarter are both included.
 
 | Transform | Result | Filter |
 |---|---|---|