Clarify template-data access for inline HTML components

[tormnator]

Summary

There appears to be a mismatch between current inline HTML component behavior and the documentation around component/template-data access.

In practice, inline HTML custom components appear to receive attribute/prop data only, while several docs pages imply that template data such as page metadata, YAML data, collections, and parsed content structure are available directly inside components.

This issue is meant to capture the design question and the documentation gap before deciding whether to change implementation.

Observed Current Behavior

When using an inline HTML custom component such as:

<breadcrumbs />

and defining the component in an HTML library like:

<nav :is="breadcrumbs">
  <li aria-current="page">{ title }</li>
</nav>

page data like title, dir, slug, etc. do not appear to be available automatically inside the component instance.

However, if values are passed explicitly as attributes/props, they do work:

<breadcrumbs url="{ dir }" title="{ title }" />

or, likely more idiomatically:

<breadcrumbs :url="{ dir }" :title="{ title }" />

Why This Is Surprising

The following docs suggest broader data availability:

• layout-system.md
• template-data.md
• interactive-components.md
• nuemark-syntax.md

In particular, interactive-components.md says components receive data from YAML files, page front matter, collections, and parsed content structure.

template-data.md also shows breadcrumb/navigation examples using dir and slug as if they are directly available in component/template context.

Important Distinction: Regular Attributes vs Colon Attributes

A useful nuance that should be documented clearly:

• Regular dynamic attributes like title="{ title }" pass the evaluated value into the component and render that attribute into the DOM.
• Colon attributes like :title="{ title }" pass the evaluated value as component data without rendering the prop as a DOM attribute.

This is useful and worth documenting whether or not implementation changes.

Design Question

Should inline HTML custom components automatically inherit template data, or should they remain attribute-prop driven by design?

Arguments for keeping current behavior

• Clearer component boundaries
• Lower collision risk between component props and page/template data
• Easier reasoning about where component values come from
• Better alignment with explicit data flow
• Nue performance is a primary feature of the framework, so any broad context inheritance should be evaluated carefully for overhead and repeated merge costs

Arguments for changing behavior

• Better alignment with current documentation/examples
• More convenient authoring for small shared components
• More consistent expectations with layout/template rendering and Nuemark examples

Main Risks if Implementation Changes

1. Regressions from name collisions, especially keys like title, description, dir, slug, url, headings, collection names, etc.
2. Ambiguity around precedence between explicit props and inherited data
3. Possible performance penalty if large template contexts are copied/merged into many component instances
4. Loss of explicitness in component APIs

Possible Paths Forward

Option 1: No implementation change

Keep inline HTML custom components attribute-prop driven and update docs to state that clearly.

This would also be a good place to document the difference between regular attributes and colon attributes.

Option 2: Inherit template data directly

Make inline HTML custom components automatically inherit page/template data in addition to explicit props.

If this is done, prop precedence should likely remain:

1. explicit component props/attributes
2. inherited template data

Option 3: Inherit template data under a namespace

To reduce collision risk, inherited ambient data could be exposed under a namespace such as:

• page.title
• page.dir
• page.slug

or

• data.title
• data.dir
• data.slug

This may preserve convenience while minimizing collisions, though it would add a second access model and would require documentation updates.

Recommendation

If implementation is not changed now, the docs should be updated to reflect current behavior and explicitly document:

• inline HTML components are prop-driven
• regular attributes vs colon attributes
• when to pass page/template data explicitly

If implementation is changed later, the collision and performance implications should be tested carefully because framework performance is a core Nue value.

[tormnator]

Related to #6, but orthogonal.

This issue is about whether inline HTML components should have access to page/template data, and if so, how that access should work.

Issue #6 is about proper ESM/module support for inline HTML component scripts.

If option 2 or 3 here is implemented, that may open up an additional workaround for some of the use cases in #6, because shared helper functions could then be exposed through template data and consumed from components that inherit that data.

That said, this issue should still be evaluated on its own merits. Template-data inheritance is not the same thing as component-script module support, and it should not be treated as the primary justification for changing component data access behavior.

[tormnator]

This issue now appears broader than just “HTML components do not inherit page/template data”.

After tracing both render paths, the current behavior seems to be inconsistent depending on where the same HTML-defined component is called from:

1. HTML invocation path: An HTML component used from another HTML template currently receives evaluated call-site attribute data only, plus renderer-injected helpers. It does not automatically inherit the full outer page/template data object.
2. Nuemark invocation path: An HTML component used as a Nuemark custom tag appears to receive a much richer input object. The Nuemark tag renderer first builds tag data from outer page data plus tag-provided values, and that merged object is then forwarded into the HTML component render call.

In other words, the same HTML component can currently see very different template context depending on whether it is invoked from HTML or from Nuemark.

That seems like an important architectural/documentation gap:

• HTML-used components are effectively explicit-prop driven
• Nuemark-used components appear to inherit page/site data through the tag bridge
• current docs lean toward the richer model in several places, which may be why the difference is surprising

This strengthens the case for clarifying or revisiting the intended model in this issue.

Relevant implementation points I checked locally:

• render-tag.js: Nuemark tag render merges outer page data into tag data before rendering
• page.js: Nuemark custom-tag bridge forwards that merged data object into renderNue
• node.js: HTML component render path builds child component data from getAttrData on the call site

So the design question is not only whether HTML components should inherit template data, but also whether HTML and Nuemark invocation paths should expose the same component context model.

Relevant code references from the repo are nue/packages/nuemark/src/render-tag.js, nue/packages/nuekit/src/render/page.js, and nue/packages/nuedom/src/dom/node.js.