How does a component declare an input as required, optional or defaulted, and where is each rule enforced?

## The declaration is a contract An input declaration names a value and states three things about it: what shape it accepts, whether the caller must supply it, and what happens when the caller does not. Together those declarations form the component's public surface — the only legal way in. Treat that surface the way you would a published function signature, because callers you cannot see are compiled against it. The three kinds: - **Required** — the component has no sensible rendering without it. A row cannot render without the record it displays. - **Optional** — absence is a real, handled case with its own behaviour, distinct from any concrete value. A missing label means render no label. - **Defaulted** — absence means one specific stated value. A missing size means the medium size, and every reader downstream sees "medium", not "absent". A subtle but common design error is declaring an input both required *and* defaulted. If the component can always fall back, the caller does not have to supply it, so it is optional with a default; keeping "required" is a lie in the contract that reviewers and tooling will trip over. ## Where each rule is actually enforced | enforcement point | when it runs | what it catches | what it misses | |---|---|---|---| | static type check | build time | a compiled caller that omits a required input or passes the wrong shape | anything not compiled against the declaration — dynamically assembled markup, values widened to an opaque shape, data from a network payload | | runtime validator | instance creation / input update | the actual value that arrived, including data that came from outside the build | nothing, but it usually only *reports* — and in many setups only in development builds | | the component's own guard | render time | the case the two above let through | nothing, but it costs a branch and a decision about what to render instead | The practical consequence: a build-time check is a *developer* tool, and a runtime validator is a *data* tool. They answer different questions and a component at the edge of the system — one fed by a response body, a query string or a persisted preference — needs the second even when the first is green. ## Absent is not the same as blank Three caller situations look alike and are not: 1. The input is **not passed at all** — the default applies. 2. The input is passed with an **explicit blank value** — in most runtimes the blank is a real value, so the default does not apply and the component receives the blank. 3. The input is passed a **value that is present but meaningless** for the domain — an empty list, a zero, an empty string. Nothing in the framework treats these as absent; only the component's own logic can. This is the source of a whole family of bugs where a value computed as blank by a caller erases a component's default. Decide explicitly, in the component, whether a blank should be coalesced to the default, and state the decision in the input's documentation. ## Traps around defaults - **A shared mutable default.** If a default is a single object or array created once with the declaration rather than per instance, every instance that omits the input gets the *same* object. One instance mutating it changes what every other instance sees. Produce the value per instance instead. - **A default that depends on another input.** A derived fallback is not a default; it is a computed value the component should derive on every update, or it goes stale when the other input changes. - **Changing a default is a breaking change.** Callers depending on the old fallback all change behaviour at once, and nothing in a build will point at them. - **A default that hides a missing required value.** A fallback chosen to stop a crash turns a loud contract violation into a screen that quietly shows the wrong thing. ## Validation is about the entry, not the lifetime Both kinds of check look at a value as it arrives. Neither watches what happens to it afterwards, so neither catches a child mutating the object it was handed, and neither catches a caller mutating the object *after* handing it down. Entry checks bound the contract; the read-only convention protects it afterwards. ## How to choose Make an input required when there is no honest rendering without it, and let the violation be loud. Default it when a single value is genuinely the common case and the component owns that opinion. Keep it optional with an explicitly handled absent case when the two branches really differ visually or behaviourally — because collapsing them into a default is how a component ends up rendering something plausible instead of reporting that a caller is wrong.