Function validateDeclaration

Narrows an unknown value read from a library's pass-through slot into a validated declaration, or null.

A co-located block is untyped in plain JS, so this read-time check is the only defence an author has against a typo. It warns once per distinct problem and never throws: a binder that throws takes the host page down, so every failure degrades to the undeclared reading instead.

What it checks, and what each failure costs:

• A block that is not an object, or whose type names no variant, is rejected outright, and the caller falls through to its chart-level declaration and then to its heuristic. A TraceType value with no variant in MaidrTraceDeclaration — 'bar', say — is unknown in the same sense: there is nothing here to declare about it.
• A key the variant does not accept is warned about and left alone; the declaration still stands and its known fields are still read.
• A key whose value is not the kind it takes is warned about and dropped, so the grammar's own default applies — the truthful smaller reading. This is what stops significanceDirection: 'Below' from being read as 'above' and announcing precisely the points that failed to reach significance as the findings.
• A variant missing a key it cannot be read without — dimensions on a parallel plot, group on a ridgeline — is rejected. The alternative is returning a block typed as if the field were there, which is an invitation to the throw this function exists to prevent.
• A variant outside the reads set — a choropleth declared on a library that draws no map — is reported with warnUndrawnType and rejected. Every adapter reads some subset and each was otherwise hand-writing the same narrowing predicate after this returned, along with its own wording for the one sentence spec §7.1 fixes.

undefined and null are "not given" wherever they appear, both as the block and as any key's value.

The returned declaration is the block itself where nothing was dropped, and a copy without the dropped keys otherwise: the author's chart config is never mutated.

This is the only place an unknown from a chart config is narrowed; any must not escape it. The "each distinct warning at most once per chart per binding" contract holds however often this is called, since every warning it raises is keyed on the author's own block — an adapter that resolves declarations at two entry points per binding needs to arrange nothing.