Component contracts: constraints on a parameter's value (one-of, type)

[fcapolini]

Version: @markout-lang/core 0.3.0

A <:define> can give a parameter a default, and that is the whole of what it
can say about it. It cannot say a parameter is required, that it accepts
one of a set, or that its parameter list is closed. So a usage site has
several ways to be wrong that all compile clean and render something.

Repro

<:define tag="ui-btn:a"
  :variant=${'primary'}      // primary | outline | ghost -- a comment, not a rule
  :label=${''}               // required in practice, no sensible default
  class=${`btn btn-${variant}`}
><:slot /></:define>

<ui-btn id="ok"      :variant="outline">Fine</ui-btn>
<ui-btn id="typo-v"  :variant="primry">Misspelled value</ui-btn>
<ui-btn id="typo-n"  :varaint="outline">Misspelled parameter name</ui-btn>
<ui-btn id="missing">No label passed</ui-btn>
<ui-btn id="wrongty" :variant=${42}>Wrong type</ui-btn>

Actual

Compiles clean, five pages of nothing said:

id	rendered class	what went wrong
ok	btn btn-outline	—
typo-v	btn btn-primry	a class with no rule; button renders unstyled
typo-n	btn btn-primary	asked for outline, got primary
missing	btn btn-primary	no label, and nothing wanted one
wrongty	btn btn-42	a number where a variant name goes

typo-n is the worst of them: the author wrote a value, the page ignored it,
and the element silently took its default.

What narrows it

• :varaint is not ignored — it creates a value. With :aka="b" on the
  usage site, ${b.varaint} reads outline. So a usage site adding a value is
  a real capability and unknown attributes cannot simply be rejected; what is
  missing is a way for a definition to say its list is closed.
• This is the compiler's own standard, unmet. An unknown reference is a
  compile error anywhere it is written, handler bodies included. An unknown
  parameter at a usage site is accepted in silence. Same class of mistake,
  opposite treatment.
• It fits silent-failures.md's admission rule exactly — a correct-looking
  page produces wrong output and nothing anywhere says why — but it sits at the
  component-contract level rather than between two framework features, which
  may be why it has not surfaced there.

Why this language is unusually well placed to fix it

Reactive values are declared in markout rather than in JavaScript, so the
compiler already owns every declaration and already resolves every name — the
same property that lets it catch Unknown reference: "cuont" inside a handler
body. Constraining a parameter is an extension of machinery that exists, not a
type layer bolted alongside. A JS-hosted framework needs TypeScript and a build
story to get the same thing.

Possible spellings, not a proposal

Recorded only so the trade-offs are visible; the shape is yours to choose.

• Required: a parameter declared with no default is required, and omitting
  it is an error. Cheap, but it changes what :x alone means today.
• A set: :variant=${'primary'} :variant-oneof=${['primary','outline','ghost']},
  checked when the usage site passes a literal and skipped when it passes an
  expression. Catches typo-v and wrongty, and only where it can be sure.
• Closed list: an opt-in on the definition — every :name at a usage site
  must be a declared parameter. Catches typo-n, which is the one that changes
  what renders. Opt-in because adding values at a usage site is deliberate
  elsewhere.

The three are independent and the third is the one with the highest ratio of
bugs caught to syntax added.

[fcapolini]

The blocker, and two ways past it

The three spellings above were written before the real constraint was clear.
A closed parameter list cannot simply reject unknown attributes, because
declaring a value on any element is core semantics — including on an element
that happens to be a custom tag. <ui-btn :varaint="outline"> is a legal value
declaration on that instance, not a malformed call, and ${b.varaint} reads it
back. A typo and a deliberate extra value are the same construct.

So the question is not "how do we reject unknown names" but "how does a usage
site say which of the two it meant".

What the site already does

Measured over this repository (8 definitions, 73 usage sites, 64 of them
carrying at least one : value):

• 0 usage sites pass a name the definition does not declare.
• Every definition splits cleanly by prefix: 20 unprefixed values that are
  the interface, 10 _-prefixed that are internals. No exceptions.
  ui-btn declares variant, size, icon, block, extra and _class;
  site-nav declares current, home and _items, _open, _panel, _prefix.

The convention exists and is airtight in practice. It just has no teeth — _
carries no meaning in the language today: an outer scope reads t._priv
happily, and a usage site can override :_priv.

So the ambiguous capability this blocker protects is used zero times in
~4,000 lines of real site.

Option A — opt-in closure, no escape

A definition marks itself closed. Any undeclared :name at a usage site is
then an error. That component loses the extra-value capability entirely.

Option B — formalise _ on both sides

One meaning, "underscore is not part of the interface", read the same way at
both ends:

	:name	:_name
in a definition	a parameter — the interface	private internal
at a usage site	a parameter, must be declared	a local value on this instance

The escape hatch survives: someone who wants an extra value writes :_mine and
says so — which reads better than today, where nothing distinguishes it from a
typo.

	A: opt-in closure	B: _ formalised
new syntax	one marker on <:define>	none — convention exists
breaking	no, opt-in	yes — any non-_ extra value
keeps the capability	no, for closed components	yes
kits need auditing	no	yes

A first looks right: non-breaking, no naming rule, and real use decides
whether anyone misses the escape before _ gets burned for it.

Worth doing either way

Marking parameters in the definition is the missing input for editor
tooling. The extension cannot offer completions for <ui-btn today because
nothing says variant, size, icon, block, extra are the interface and _class
is not. A declared parameter list buys completion, hover docs, and "unknown
parameter" as a squiggle rather than a build error — plausibly a bigger
day-to-day win than the checking, and it argues for doing the definition half
whichever usage-site rule wins.

[fcapolini]

Most of this shipped in 0.5.0, and it is close to Option A as argued here — so this issue now overstates what is missing. Narrowing it rather than closing it, because the part that is left is real.

A <:define> states its interface with ::, and the tag reserves those names. Re-running this issue's repro against main:

id	what went wrong	today
typo-n	misspelled parameter name	error — <ui-btn> has no parameter "varaint": it takes "variant", "label"
typo-n as plain :varaint	ditto, other spelling	warning — nothing reads "varaint", declared on <ui-btn>
typo-v	misspelled value, ::variant=${'primry'}	still silent
missing	required parameter not passed	still silent
wrongty	wrong type, ::variant=${42}	still silent

So "the parameter list is closed" is done, and without the tradeoff table above having to be resolved: the escape hatch survives with no naming rule burned, because :name at a usage site is a local on that instance and ::name is the interface. Two spellings, so nothing has to be inferred from an underscore. _ stays a convention meaning "the component's own business" and carries no rule, which is what this issue wanted from Option B without the breaking change.

The "worth doing either way" paragraph also landed: PARAMETER_MARKER is exported from @markout-lang/core and packages/vscode/src/completions.ts uses it, so a usage site offers the parameters a definition declares.

What is actually left

Contracts on the value, not on the name:

• required — a parameter with no sensible default, whose absence should be an error rather than undefined
• one of a set — variant is primary | outline | ghost, and today that is a comment
• type — ::variant=${42} renders btn btn-42

These are a much narrower and more debatable feature than closing the name list was, and worth deciding separately. The obvious tension: this project's position is that ${…} is plain JavaScript with no separate expression language, and every shape of "declare what this accepts" is some amount of type system. Worth saying which of the three is wanted before designing any of them — required is the one with no design space to speak of and the clearest failure today.

[fcapolini]

Required is now split out as #46, leaving this issue the value-level half — one-of and type — as the comment above proposed.

Retitled to match. The old title claimed the name-level gap too, which :: closed in 0.5.0.

#46 argues for the no-syntax spelling: a declaration with no default is required. The measurement behind it, since the comment above left the spelling open — across the 31 files in kits/ containing a <:define> there are 251 :: parameter declarations and every one carries a default, so no bare declaration exists to break. And the shape being repurposed is currently worse than unused: a bare declaration today means default true, which is backwards for the boolean flags it would otherwise serve.