feat: Expose host:tagName on Components (#758)

* Add as attribute and better TagName type

* 😃

* 💡

* Expose tagName on Host component and host:tagName

* Fix host:tagName

* Unit Tests

* Tests and Docs

* Remove duplicated type definitions

* ❤️

* Remove last duplicated type

* 😛

* New implementation

* Unit tests

* Remove <Host tagName=""/> docs

* Api update

* Last bad doc reference

Co-authored-by: GlennBecker <logosbyglenn@gmail.com>

Author: nnelgxorz

packages/docs/src/pages/docs/components/anatomy.mdx

@@ -100,7 +100,7 @@ Will result in:
 
 Qwik host elements are marked with `q:host` attribute.
 
-As you can see, `component$` will always create an extra element, by default is `div`, but that can be changed with `component$` options argument:
+As you can see, `component$` will always create an extra element, by default is `div`, but that can be changed with `component$` options argument or the `host:tagName` attribute:
 
 ```tsx
 const MyArticle = component$(() => (
@@ -110,7 +110,17 @@ const MyArticle = component$(() => (
 });
 ```
 
-Will result in:
+and:
+
+```tsx
+const MyArticle = component$(() => (
+  <span>My article</span>
+));
+
+<MyArticle host:tagName="article"/>
+```
+
+Will both result in:
 
 ```html
 <article q:host>
@@ -126,9 +136,6 @@ Since the host element is implicitly created by `component$`, it is not possible
 
  Qwik uses host elements in various ways. For example when using `useHostElement()` function which retrieves it. It is also used to attach props to the components for serialization.
 
-
-
-
 ## Host Element Attributes & Styling
 
 Assume you have a component defined as so:
@@ -230,7 +237,6 @@ will result in:
 </div>
 ```
 
-
 ## Lazy Loading
 
 The host component also serves an important role when breaking parent-child relationships for bundling purposes.

packages/qwik/src/core/api.md

@@ -70,7 +70,8 @@ export type Component<PROPS extends {}> = FunctionComponent<PublicProps<PROPS>>;
 
 // @public
 export interface ComponentOptions {
-    tagName?: string;
+    // Warning: (ae-forgotten-export) The symbol "JSXTagName" needs to be exported by the entry point index.d.ts
+    tagName?: JSXTagName;
 }
 
 // @public

packages/qwik/src/core/component/component.public.ts

@@ -1,7 +1,7 @@
 import { $, QRL } from '../import/qrl.public';
 import type { JSXNode } from '../render/jsx/types/jsx-node';
 import { OnRenderProp } from '../util/markers';
-import type { ComponentBaseProps } from '../render/jsx/types/jsx-qwik-attributes';
+import type { ComponentBaseProps, JSXTagName } from '../render/jsx/types/jsx-qwik-attributes';
 import type { FunctionComponent } from '../render/jsx/types/jsx-node';
 import { jsx } from '../render/jsx/jsx-runtime';
 import type { MutableWrapper } from '../object/q-object';
@@ -42,7 +42,7 @@ export interface ComponentOptions {
    * of host element requires that the parent component needs to know the tag name of the child
    * component synchronously.
    */
-  tagName?: string;
+  tagName?: JSXTagName;
 }
 
 /**
@@ -80,7 +80,7 @@ export type MutableProps<PROPS extends {}> = {
  */
 export type EventHandler<T> = QRL<(value: T) => any>;
 
-const ELEMENTS_SKIP_KEY = ['html', 'body', 'head'];
+const ELEMENTS_SKIP_KEY: JSXTagName[] = ['html', 'body', 'head'];
 
 // <docs markdown="../readme.md#component">
 // !!DO NOT EDIT THIS COMMENT DIRECTLY!!!
@@ -145,8 +145,9 @@ export const componentQrl = <PROPS extends {}>(
 
   // Return a QComponent Factory function.
   return function QSimpleComponent(props, key): JSXNode<PROPS> {
+    const finalTag = props['host:tagName'] ?? tagName;
     const finalKey = skipKey ? undefined : onRenderQrl.getHash() + ':' + (key ? key : '');
-    return jsx(tagName, { [OnRenderProp]: onRenderQrl, ...props }, finalKey) as any;
+    return jsx(finalTag as string, { [OnRenderProp]: onRenderQrl, ...props }, finalKey) as any;
   };
 };
 

packages/qwik/src/core/render/jsx/host.public.ts

@@ -4,6 +4,7 @@ import type { FunctionComponent } from './types/jsx-node';
 export interface HostAttributes extends HTMLAttributes<HTMLElement> {
   [key: string]: any;
 }
+
 /**
  * Place at the root of the component View to allow binding of attributes on the Host element.
  *

packages/qwik/src/core/render/jsx/types/jsx-qwik-attributes.ts

@@ -180,6 +180,11 @@ interface CSSProperties {
   [key: string]: string | number;
 }
 
+/**
+ * @public
+ */
+export type JSXTagName = keyof HTMLElementTagNameMap | Omit<string, keyof HTMLElementTagNameMap>;
+
 /**
  * @public
  */
@@ -207,6 +212,7 @@ export interface ComponentBaseProps {
   [key: `preventDefault:${string}`]: boolean;
   [key: `preventdefault:${string}`]: boolean;
 
+  'host:tagName'?: JSXTagName;
   children?: JSXChildren;
 }
 export interface QwikAttributes extends QwikProps, QwikEvents {}

packages/qwik/src/core/render/render.unit.tsx

@@ -90,7 +90,6 @@ renderSuite('should serialize events correctly', async () => {
     ></Div>
   );
 });
-
 renderSuite('should serialize boolean attributes correctly', async () => {
   const fixture = new ElementFixture();
   await render(fixture.host, <input required={true} disabled={false}></input>);
@@ -107,7 +106,12 @@ renderSuite('should render into a document', async () => {
   );
   equal(fixture.document.body.innerHTML, 'WORKS');
 });
-
+renderSuite('should accept and render host:tagName', async () => {
+  const fixture = new ElementFixture();
+  const tag: keyof HTMLElementTagNameMap = 'article';
+  await render(fixture.host, <HelloWorld host:tagName={tag} />);
+  equal(getFirstNode(fixture.host).tagName, tag.toUpperCase());
+});
 renderSuite('should render attributes', async () => {
   const fixture = new ElementFixture();
   await render(fixture.host, <div id="abc" title="bar" preventdefault:click></div>);