What must a wrapper component forward so that callers of the component it wraps cannot tell the wrapper is there?

## What a wrapper is for A **wrapper** — pass-through component, decorator, higher-order component; the names vary by community — is a component whose job is to render another component and add something around it: an access check, error handling, instrumentation, a layout shell, an adapter that translates one input shape into another. It is the composition answer to needing this component plus this behaviour everywhere. The wrapper's entire value is that callers should not have to care. If using the wrapped component through the wrapper differs from using it directly, every consumer pays for the wrapper's existence. ## The four things a transparent wrapper forwards 1. **Inputs and attributes it does not consume.** The wrapper declares the few it reads and passes the rest down untouched, including plain markup attributes and accessibility attributes, which are exactly what callers reach for. 2. **Event bindings.** A handler the caller attached must reach the inner component's corresponding output. Dropping one produces the worst kind of bug: a control that looks right and reports nothing. 3. **Every content region, by name.** A wrapper that forwards only the default region silently deletes the header and footer the inner component published. 4. **The escape hatch to the real element.** When callers need to focus, measure or scroll the underlying node, the wrapper must hand that handle through — its own markup is not what the caller asked for. ## The three leaks, and how each looks in review | Leak | Symptom | Fix | |---|---|---| | Swallowed input | the caller sets something and nothing happens | forward the unconsumed remainder rather than a hand-written list | | Lost content region | named regions render empty through the wrapper | forward regions by name, including ones added later | | Broken element access | the caller cannot focus or measure the control | hand the inner element's handle through | A quieter fourth is a **name collision**: the wrapper declares an input the inner component also uses. One of them wins, the caller cannot tell which, and adding an input to the inner component can break a wrapper that was correct yesterday. Prefix or namespace the wrapper's own inputs, and keep them few. ## What the projected subtree keeps Content the caller passes *through* a wrapper is still the caller's content: - It was created in the caller's scope and resolves its names there, wherever the wrapper ends up rendering it. - It keeps its identity when the wrapper re-renders for its own reasons, so stateful things inside it — an open menu, a half-typed value, a scroll offset — survive. - Where it sits in the **component tree** decides what it reads from ancestors; that lookup has its own rules and its own topic. So a wrapper is free to re-render, but it is not free to re-parent content casually: moving where the content lands changes what it inherits from the tree around it. ## When a wrapper should stop pretending to be transparent Not every wrapper is a pass-through, and pretending otherwise is worse than being explicit: - A **gate** may render a denial instead of the child. That is a decision, not decoration. - A **boundary** may replace a failed subtree with a recovery surface. - An **adapter** deliberately changes the API: a different input shape, a narrower surface, renamed events. These should be named for the decision they make, keep a small explicit API, and be documented as not invisible. The failure mode to avoid is a wrapper that is transparent in most cases and quietly opinionated in one. ## Practical habits - Forward the **remainder**, never an enumerated list: a list goes stale the first time the inner component gains an input. - Add a test that sets an input the wrapper knows nothing about and asserts it arrived at the inner component. - Keep a wrapper to **one** added behaviour. Two behaviours are two wrappers, or better, one reusable unit and one wrapper. - Count your layers: each one is another contract to keep in sync, another namespace to collide in, and another hop for whoever is reading the tree. ## Where runtimes differ The mechanics of the remainder and of an element handle are per-runtime. Some spread unconsumed inputs automatically onto the root element the wrapper renders, some require an explicit rest-and-spread step, and some make the wrapped component opt in before a handle can be exposed at all. The contract is constant — consume what you use, forward the rest — and only the amount of ceremony changes.