Document the :bind feature explicitly

[tormnator]

Is your feature request or improvement related to a problem?

Yes.

The :bind feature exists in Nue and is useful, but it does not appear to be documented clearly enough today. There is a brief example in html-syntax.md, but not a proper explanation of what :bind does, how it differs from regular bound props, or when it should be used.

This creates avoidable confusion because :bind is not just an arbitrary bound attribute name. It has special merge behavior in the renderer.

In practice, this makes questions like these harder than they should be:

• Is :bind a real Nue feature or just a naming convention?
• What is the difference between :bind="item" and :item="item"?
• What is the difference between :bind="{ foo }" and :foo="foo"?
• When should implementers use :bind instead of explicit prop passing?

Solution you'd like

Document :bind explicitly as a first-class Nue feature.

At minimum, the docs should explain:

• :bind is special-cased by Nue
• the bound expression is evaluated and, if it resolves to an object, its properties are merged into the child component data/context
• this is different from a normal bound attribute like :foo="bar", which assigns one property named foo
• :bind can be used to pass many values at once or to forward an existing object/context subset into a child component

Why this matters

Right now, readers can infer some behavior from examples, tests, or source code, but that is not enough for a feature this semantics-sensitive.

For example, these are not equivalent:

<child :bind="{ helper }" />
<child :helper="helper" />

They may both expose helper to the child, but they do so through different mechanisms. And this is also different again:

<child :helpers="{ helper }" />

which sets one property called helpers whose value is an object.

That distinction is important for both API design and readability.

Existing evidence in the repo

Current documentation example:

<product-card :each="item in products" :bind="item"/>

Implementation behavior is special-cased in the renderer. In getAttrData, bind is merged into the child data rather than assigned as a normal prop.

There are also direct tests for :bind behavior in packages/nuedom/test/component.test.js.

Suggested doc additions

A short dedicated subsection in the HTML/component syntax docs would probably be enough. For example:

• what :bind does
• how it differs from normal bound props
• a simple object example
• a component forwarding example
• any caveats, such as preferring explicit props when a narrower API is clearer

Alternatives you've considered

1. Leave it implicit in examples

This is the current situation, but it leaves too much room for uncertainty around a special feature.

2. Only document it in API/reference style docs

Better than nothing, but a short explanation near component prop examples would likely help more readers discover it at the moment they need it.

Additional context

This is a documentation issue, not necessarily a request to change implementation. The current behavior already seems intentional and useful; the missing piece is making it explicit in the docs.